/// @page page_field_tutorial fields_type Definition Tutorial
/// @tableofcontents
/// fields_type are abstractions around value storage primitives and/or objects,
/// such as integral values, floating point values, strings, arrays, etc..
/// Every @b field class is defined in @ref nil::marshalling::field namespace and
/// exposes predefined interface in order to
/// make template meta-programming as easy as possible. As an example let's
/// take a look at @ref nil::marshalling::types::IntValue class which is used to
/// define integral value field.
/// @code
/// template <typename TBase, typename T, typename... TOptions>
/// class nil::marshalling::types::IntValue : public TBase
/// {
/// public:
///     // Define inner storage type
///     using value_type = T;
///
///     // type used for version update
///     using version_type = typename TBase::version_type;
///     
///     // Get access to the stored value
///     value_type& value() { return m_value; }
///     const value_type& value() const { return m_value; }
///
///     // Read
///     template <typename TIter>
///     nil::marshalling::ErrorStatus read(TIter& iter, std::size_t len) {...}
///
///     // Write
///     template <typename TIter>
///     nil::marshalling::ErrorStatus write(TIter& iter, std::size_t len) const {...}
///
///     // Serialisation length
///     std::size_t length() const {...}
///
///     // Validity of the value
///     bool valid() const {...}
///
///     // Bring field's contents into a consistent state
///     bool refresh() {...}
///
///     // Update protocol version
///     bool set_version(version_type value) {...}
///
///     // Compile time check whether the field's contents may change as the
///     // result of protocol version update
///     static constexpr bool is_version_dependent() {...};
///
/// private:
///     value_type m_value;
/// }
/// @endcode
/// The main things to note are that every field definition class:
/// @li receives its base class as the first 
///     template parameter. It is expected to be a variant of @ref
///     nil::marshalling::field_type with @ref nil::marshalling::option::big_endian or @ref
///     nil::marshalling::option::little_endian option to specify the serialization endian.
/// @li exhibits some default behaviour which can be modified by
///     passing various options from @ref nil::marshalling::option namespace as additional template
///     parameters. All the available options are described below in this tutorial.
/// @li defines @b value_type inner value storage
///     type and provides @b value() member functions to access the stored value.
/// @li provides @b read() and @b write() member functions to read and write the 
///     inner value given the iterator used for reading / writing and available
///     length of the buffer.
/// @li has @b length() member function to report how many bytes are required to
///     serialise currently stored value.
/// @li provides @b valid() member function to check whether the stored value is
///     valid (within expected range of values).
/// @li has @b refresh() member function to bring its contents to consistent / valid
///     state when required.
/// @li has @b set_version() member function to notify field object that the
///     the protocol version has changed.
///
/// Also note that all the member function are NON-virtual, i.e. the field 
/// abstractions do not have polymorphic behaviour.
///
/// The available fields abstractions are:
/// @li @ref nil::marshalling::types::IntValue - used to define @ref sec_field_tutorial_int_value
/// @li @ref nil::marshalling::types::EnumValue - used to define @ref sec_field_tutorial_enum_value
/// @li @ref nil::marshalling::types::BitmaskValue - used to define @ref sec_field_tutorial_bitmask_value
/// @li @ref nil::marshalling::types::Bitfield - used to define @ref sec_field_tutorial_bitfield
/// @li @ref nil::marshalling::types::Bundle - used to define @ref sec_field_tutorial_bundle
/// @li @ref nil::marshalling::types::array_list - used to define @ref sec_field_tutorial_array_list
/// @li @ref nil::marshalling::types::String - used to define @ref sec_field_tutorial_string
/// @li @ref nil::marshalling::types::FloatValue - used to define @ref sec_field_tutorial_fp_value
/// @li @ref nil::marshalling::types::Optional - used to define @ref sec_field_tutorial_optional
/// @li @ref nil::marshalling::types::Variant - used to define @ref sec_field_tutorial_variant
///
/// @section sec_field_tutorial_int_value Integral value fields_type
/// Integral values are abstracted by nil::marshalling::types::IntValue class, which
/// receives at least two template parameters. The first one is a base
/// class, from which the nil::marshalling::types::IntValue will inherit. It must be
/// a variant of nil::marshalling::field_type, with the option specifying endian used for
/// data serialization. The second template parameter is a basic integral type
/// that is used to store the field's value.@n
/// For example:
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using MyIntField = nil::marshalling::types::IntValue<MyFieldBase, std::int16_t>;
/// @endcode
/// The example above defines a field that uses @b std::int16_t type to store
/// its value. The value can be accessed using @b value() member function:
/// @code
/// MyIntField intField;
/// std::cout << "Default value: " << intField.value() << '\n'; // prints 0
/// intField.value() = 5;
/// std::cout << "Updated value: " << intField.value() << std::endl; // prints 5
/// @endcode 
/// When such field is serialized, 2 bytes (<b>sizeof(std::int16_t)</b>) are written
/// to the output buffer, most significant first and less significant second
/// (because @b MyFieldBase base class was defined using nil::marshalling::option::big_endian
/// option).
/// 
/// @subsection sec_field_tutorial_int_value_fixed_length Modifying Serialisation length
/// Sometimes protocol specification tries to reduce amount of data transferred over
/// I/O link. It may define serialization length of the field that differs
/// from standard length of basic integral types, such as @b std::int8_t, @b std::uint8_t,
/// @b std::int16_t, @b std::uint16_t, @b std::int32_t, @b std::uint32_t, ...
/// For example, some field may only have values between 0 and 10,0000,000, which
/// may be encoded using only 3 bytes, and that's what the protocol specifies.
/// The storage type for such value is going to be @b std::uint32_t, but there is
/// a need to limit serialization length for it. The Marshalling library provides
/// nil::marshalling::option::fixed_length option, that can be used for this purpose.
/// @code
/// using MyIntField = nil::marshalling::types::IntValue<MyFieldBase, std::uint32_t, nil::marshalling::option::fixed_length<3> >;
/// @endcode
///
/// @subsection sec_field_tutorial_int_value_var_length Variable Serialisation length
/// There are protocols, that try to reduce amount of traffic over I/O link by
/// using variable length when serialising numeric value. Usually it is
/// <a href="https://en.wikipedia.org/wiki/Variable-length_quantity">Base-128</a>
/// encoding, where the most significant bit in the byte indicates whether
/// it is the last byte in the numeric encoding or the next one also needs to
/// be taken into account. The Marshalling library provides nil::marshalling::option::var_length
/// option that can be used with nil::marshalling::types::IntValue and modifies the
/// behaviour of the latter to expose the required read()/write()/length() 
/// behaviour:
/// @code
/// // Variable length encoding, encoding takes at least 1 byte and at most 4 bytes. 
/// using MyIntField = nil::marshalling::types::IntValue<MyFieldBase, std::uint32_t, nil::marshalling::option::var_length<1, 4> >;
/// @endcode
/// The field's base class (@b MyFieldBase) contains endian information which is
/// used to determine which part of the value is serialized first.
///
/// @subsection sec_field_tutorial_int_value_ser_offset Serialisation Offset
/// There are cases when there is a need to add/subtract some predefined offset
/// to/from the value of the field when serialization takes place.
/// Good example of such case would be serialising a "current year" value. 
/// Most protocols now specify it as an offset from year 2000 or later and 
/// serialized as a single byte, i.e. to specify year 2015 is to write value 15.
/// However it may be inconvenient to manually adjust serialized/deserialized
/// value by predefined offset 2000. To help with such case option 
/// nil::marshalling::option::num_value_ser_offset can be used. For example:
/// @code
/// using YearField = 
///     nil::marshalling::types::IntValue<
///         MyFieldBase, 
///         std::int16_t, 
///         nil::marshalling::option::fixed_length<1>,
///         nil::marshalling::option::num_value_ser_offset<-2000>
///     >;
///
/// static const std::uint8_t SerData[] = { 15 }; // Pretend serialization data
/// static const std::size_t SerDataLen = std::extent<decltype(SerData)>::value; 
/// 
/// YearField year;
/// auto* readIter = &SerData[0];
/// auto es = year.read(readIter, SerDataLen); // Read year information
/// assert(es == nil::marshalling::ErrorStatus::success); // No failure is expected
///
/// std::cout << year.value() << std::endl; // Prints 2015;
///
/// // Modify year value:
/// year.value() = 2016;
/// 
/// std::vector<std::uint8_t> outData; // Pretend output buffer
/// auto writeIter = std::back_inserter(outData);
/// es = year.write(writeIter, outData.max_size());
/// assert(es == nil::marshalling::ErrorStatus::success); // No failure is expected
///
/// assert(outData.size() == 1U); // Only 1 byte is expected to be pushed to outData,
///                               // due to using nil::marshalling::option::fixed_length<1> option.
/// assert(outData[0] == 16); // The value equal to "year.value() - 2000" is expected to be written.  
/// @endcode
///
/// @subsection sec_field_tutorial_int_value_scaling Scaling value
/// Sometimes systems operate with floating point numbers. Let's say to handle
/// the distance between two points on the map in meters. However, when communicating
/// this information over the I/O link, the developers often scale the floating
/// point value up in order to send such value as integer. For example, the distance
/// is communicated in millimeters (when calculated and handled in meters). 
/// The definition of such field may look like:
/// @code
/// using DistanceField =
///     nil::marshalling::types::IntValue<
///         MyFieldBase, 
///         std::uint16_t, 
///         nil::marshalling::option::scaling_ratio<1, 1000>
///     >;
/// @endcode
/// The nil::marshalling::option::scaling_ratio option allows scaling of serialized value
/// (distance in mm) to handling value (distance in m) and vice versa:
/// @code
/// static const std::uint8_t InData[] = {0x3, 0xe8}; // Pretend input buffer, encoded 1000
/// static const std::size_t InDataSize = std::extent<decltype(InData)>::value;
/// 
/// DistanceField dist;
/// const auto* readIter = &InData[0];;
/// auto es = dist.read(readIter, InDataSize);
/// assert(es == nil::marshalling::ErrorStatus::success); // No error is expected
///
/// std::cout << "distance in mm: " << dist.value() << '\n'; // Prints 1000
/// std::cout << "distance in m: "  << dist.get_scaled<float>() << std::endl; // Prints 1.0
///
/// dist.set_scaled(2.3);
/// std::cout << "New distance in mm: " << dist.value() << std::endl; // Prints 2300
/// @endcode
///
/// The scaling may work in the opposite direction of increasing the number. For
/// example, the field contains number of @b tens of millimeters between two points.
/// It would be convenient to be able to convert it to proper millimeters number.
/// As the result the field can be defined as:
/// @code
/// using OtherDistanceField = 
///     nil::marshalling::types::IntValue<
///         MyFieldBase, 
///         std::uint16_t, 
///         nil::marshalling::option::scaling_ratio<10, 1>
///     >;
/// @endcode
/// The nil::marshalling::option::scaling_ratio option allows scaling of serialized value
/// (distance in tens of mm) to handling value (distance in mm) and vice verse:
/// @code
/// static const std::uint8_t InData[] = {0x0, 0xf}; // Pretend input buffer, encoded 15
/// static const std::size_t InDataSize = std::extent<decltype(InData)>::value;
/// 
/// OtherDistanceField dist;
/// const auto* readIter = &InData[0];;
/// auto es = dist.read(readIter, InDataSize);
/// assert(es == nil::marshalling::ErrorStatus::success); // No error is expected
///
/// std::cout << "distance in tens of mm: " << dist.value() << '\n'; // Prints 15
/// std::cout << "distance in mm: "  << dist.get_scaled<unisnged>() << std::endl; // Prints 150
///
/// dist.set_scaled(500);
/// std::cout << "New distance in tens of mm: " << dist.value() << std::endl; // Prints 50
/// @endcode
///
/// Methods nil::marshalling::types::IntValue::get_scaled and nil::marshalling::types::IntValue::set_scaled
/// take into account scaling ratio provided (with nil::marshalling::option::scaling_ratio option)
/// to the nil::marshalling::types::IntValue field. If such option wasn't used
/// @b nil::marshalling::option::scaling_ratio<1, 1> is assumed.
///
/// @subsection sec_field_tutorial_int_value_units value units
/// In addition to @ref sec_field_tutorial_int_value_scaling, the @b Marshalling library
/// provides an ability to specify field's value units and perform conversion
/// between units of the same type. Let's get back to the same example of defining
/// distance between two point, but instead of providing scaling ratio directly,
/// the type of the units is specified.
/// @code
/// using DistanceField =
///     nil::marshalling::types::IntValue<
///         MyFieldBase, 
///         std::uint16_t, 
///         nil::marshalling::option::units_millimeters
///     >;
/// @endcode
/// The nil::marshalling::option::units_millimeters option specifies that field contains
/// distance in millimeters, which allows @b Marshalling library provide proper
/// conversion to other distance units when necessary:
/// @code
/// static const std::uint8_t InData[] = {0x3, 0xe8}; // Pretend input buffer, encoded 1000
/// static const std::size_t InDataSize = std::extent<decltype(InData)>::value;
/// 
/// DistanceField dist;
/// const auto* readIter = &InData[0];;
/// auto es = dist.read(readIter, InDataSize);
/// assert(es == nil::marshalling::ErrorStatus::success); // No error is expected
///
/// std::cout << "Original value: " << dist.value() << '\n'; // Prints 1000
/// std::cout << "distance in mm: "  << nil::marshalling::units::get_millimeters<unsigned>(dist) << std::endl; // Prints 1000
/// std::cout << "distance in cm: "  << nil::marshalling::units::get_centimeters<float>(dist) << std::endl; // Prints 100.0
/// std::cout << "distance in m: "  << nil::marshalling::units::getMeters<float>(dist) << std::endl; // Prints 1.0
///
/// nil::marshalling::units::setCentimeters(dist, 5.5f);
/// std::cout << "New value: " << dist.value() << '\n'; // Prints 55
/// std::cout << "New distance in mm: "  << nil::marshalling::units::get_millimeters<unsigned>(dist) << std::endl; // Prints 55
/// std::cout << "New distance in cm: "  << nil::marshalling::units::get_centimeters<float>(dist) << std::endl; // Prints 5.5
/// std::cout << "New distance in m: "  << nil::marshalling::units::getMeters<float>(dist) << std::endl; // Prints 0.055
/// @endcode
///
/// In the examples above the "units" specification may replace the "scaling" 
/// information. However, there are cases when it they may complement each other.
/// For example, the field contains "latitude" information in @b degrees but
/// multiplied by 10'000'000 to make integral value out of floating point.
/// @code
/// using LatField =
///     nil::marshalling::types::IntValue<
///         MyFieldBase, 
///         std::int32_t,
///         nil::marshalling::option::scaling_ratio<1, 10000000>,
///         nil::marshalling::option::units_degrees
///     >;
/// @endcode
/// The @b Marshalling library uses the scaling ratio as well as units information to
/// be able to convert the stored value between degrees and radians when needed.
/// @code
/// LatField lat(123456789); // Encoded latitude of 12.3456789
/// std::cout << "Raw value: " << lat.value() << std::endl; // Prints 123456789
/// std::cout << "Lat in degrees: " << nil::marshalling::units::getDegrees<double>(lat) << std::endl; // Prints 12.3456789
/// std::cout << "Lat in radians: " << nil::marshalling::units::getRadians<float>(lat) << std::endl; // 0.21547274519
///
/// nil::marshalling::units::setDegrees(lat, 22.33);
/// std::cout << "New raw value: " << lat.value() << std::endl; // Prints 223300000
/// std::cout << "New degrees value: " << nil::marshalling::units::getDegrees<double>(lat) << std::endl; // Prints 22.33
/// std::cout << "New radians value: " << nil::marshalling::units::getRadians<double>(lat) << std::endl; // Prints 0.38973202
///
/// nil::marshalling::units::setRadians(lat, 1.04719);
/// std::cout << "Updated raw value: " << lat.value() << std::endl; // Prints 600000000
/// std::cout << "Updated degrees value: " << nil::marshalling::units::getDegrees<double>(lat) << std::endl; // Prints 60
/// std::cout << "Updated radians value: " << nil::marshalling::units::getRadians<double>(lat) << std::endl; // Prints 1.04719
/// @endcode
/// The @b Marshalling library provides mulitple @b options to specify the units of
/// the field's value:
/// @li @b Time:
///     - nil::marshalling::option::units_nanoseconds
///     - nil::marshalling::option::units_microseconds
///     - nil::marshalling::option::units_milliseconds
///     - nil::marshalling::option::units_seconds
///     - nil::marshalling::option::units_minutes
///     - nil::marshalling::option::units_days
///     - nil::marshalling::option::units_weeks
/// @li @b distance:
///     - nil::marshalling::option::units_nanometers
///     - nil::marshalling::option::units_micrometers
///     - nil::marshalling::option::units_millimeters
///     - nil::marshalling::option::units_centimeters
///     - nil::marshalling::option::units_meters
///     - nil::marshalling::option::units_kilometers
/// @li @b speed:
///     - nil::marshalling::option::units_nanometers_per_second
///     - nil::marshalling::option::units_micrometers_per_second
///     - nil::marshalling::option::units_millimeters_per_second
///     - nil::marshalling::option::units_centimeters_per_second
///     - nil::marshalling::option::units_meters_per_second
///     - nil::marshalling::option::units_kilometers_per_second
///     - nil::marshalling::option::units_kilometers_per_hour
/// @li @b frequency:
///     - nil::marshalling::option::units_hertz
///     - nil::marshalling::option::units_kilohertz
///     - nil::marshalling::option::units_megahertz
///     - nil::marshalling::option::units_gigahertz
/// @li @b angle:
///     - nil::marshalling::option::units_degrees
///     - nil::marshalling::option::units_radians
/// @li @b Electrical @b current:
///     - nil::marshalling::option::units_nanoamps
///     - nil::marshalling::option::units_microamps
///     - nil::marshalling::option::units_milliamps
///     - nil::marshalling::option::units_amps
///     - nil::marshalling::option::units_kiloamps
/// @li @b Electrical @b voltage:
///     - nil::marshalling::option::units_nanovolts
///     - nil::marshalling::option::units_microvolts
///     - nil::marshalling::option::units_millivolts
///     - nil::marshalling::option::units_volts
///     - nil::marshalling::option::units_kilovolts
///
/// All the units conversion functions reside in nil::marshalling::units namespace. @b NOTE,
/// that conversion can be applied only between the units of the same type. The
/// units compitability check is performed at compile time and the compilation 
/// will fail on attempt to set/get incompatible value, such as
/// setting/getting "seconds" to/from the field specified as containing millimeters.
///
/// The whole units conversion functionality can be useful in a client code,
/// that requires usage of particular unit types in its internal calculations. It
/// can use conversion functions without any need to know scaling ratio and/or
/// actual units of the field, the @b Marshalling library will do all the necessary math
/// calculation to provide the requested value.
///
/// @subsection sec_field_tutorial_int_value_other Other options_type
/// There multiple common options that are applicable to all the fields,
/// nil::marshalling::types::IntValue included. Please refer to
/// @ref sec_field_tutorial_common_options for more detail.
///
/// @section sec_field_tutorial_enum_value Enum value fields_type
/// Sometimes it is more convenient to operate with enum types instead of 
/// integral values. For example, the custom protocol message carries information
/// of how to configure some external serial port, and one of the values is
/// the baud rate. In order not to impose too much overhead on I/O link, the
/// protocol developers decided to use single byte to indicate one standard baud
/// rate:
/// |Baud Rate | Serialisation value|
/// |:--------:|:------------------:|
/// | 9600     | 0                  |
/// | 14400    | 1                  |
/// | 19200    | 2                  |
/// | 28800    | 3                  |
/// | 38400    | 4                  |
/// | 57600    | 5                  |
/// | 115200   | 6                  |
///
/// It would be more convenient to define enum type to operate with, instead of
/// using raw numbers.
/// @code
/// enum Baud : std::uint8_t // The underlying type should be explicitly specified
/// {
///     Baud_9600,
///     Baud_14400,
///     Baud_19200,
///     Baud_28800,
///     Baud_38400,
///     Baud_57600,
///     Baud_115200
/// };
///
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using BaudField = nil::marshalling::types::EnumValue<MyFieldBase, Baud>;
///
/// BaudField baud;
/// ...
/// baud.value() = Baud_115200; // Set the value.
///
/// std::vector<std::uint8_t> outData; // Pretend output buffer
/// auto writeIter = std::back_inserter(outData);
/// auto es = baud.write(writeIter, outData.max_size());
/// assert(es == nil::marshalling::ErrorStatus::success); // No error is expected
/// assert(outData.size() == 1); // Single byte output is expected
/// assert(outData[0] == 6U); // value 6 is expected to be written
/// @endcode
/// nil::marshalling::types::EnumValue is very similar to nil::marshalling::types::IntValue. The main
/// difference is using enum instead of integral type as a second template
/// parameter. The default serialization length is determined by the underlying
/// type of the enum. That't why it is important to explicitly specify the
/// underlying type of the enum when defining it, and not leave this to the
/// compiler.
///
/// The nil::marshalling::types::EnumValue field supports almost all the options that
/// can be used with nil::marshalling::types::IntValue: @ref sec_field_tutorial_int_value_fixed_length,
/// @ref sec_field_tutorial_int_value_var_length, @ref sec_field_tutorial_int_value_ser_offset,
/// as well as @ref sec_field_tutorial_common_options.
///
/// @section sec_field_tutorial_bitmask_value Bitmask value fields_type
/// Quite often messages in communication protocol use some kind of flags, where
/// single bit has a independent meaning. It is more convenient to treat
/// such flags as bitmasks rather than integral values. nil::marshalling::types::BitmaskValue
/// provides a convenient interface to handle such bitmasks.
/// @code
/// using BitmaskField = nil::marshalling::types::BitmaskValue<MyFieldBase>;
/// @endcode
/// By default the underlying storage type of the nil::marshalling::types::BitmaskValue is
/// @b unsigned, which makes the default serialization length to be
/// @b sizeof(unsigned). The modification of the underlying storage type as
/// well as serialization length can be done using nil::marshalling::option::fixed_length
/// option (see @ref sec_field_tutorial_int_value_fixed_length). The underlying
/// type will always be some unsigned integral type. If the serialization length
/// is specified to be 1 byte, the underlying storage type is @b std::uint8_t, 
/// if the serialization length is 2 bytes, the underlying storage type is @b std::uint16_t,
/// if the serialization length is 3 or 4 bytes, the underlying storage type is
/// @b std::uin32_t, etc...
/// @code
/// using BitmaskField_1byte = nil::marshalling::types::BitmaskValue<MyFieldBase, nil::marshalling::option::fixed_length<1> >;
/// static_assert(std::is_same<BitmaskField_1byte::value_type, std::uint8_t>::value, "std::uint8_t type is expected");
/// assert(BitmaskField_1byte().length() == 1U);
///
/// using BitmaskField_2bytes = nil::marshalling::types::BitmaskValue<MyFieldBase, nil::marshalling::option::fixed_length<2> >;
/// static_assert(std::is_same<BitmaskField_2bytes::value_type, std::uint16_t>::value, "std::uint16_t type is expected");
/// assert(BitmaskField_2bytes().length() == 2U);
///
/// using BitmaskField_3bytes = nil::marshalling::types::BitmaskValue<MyFieldBase, nil::marshalling::option::fixed_length<3> >;
/// static_assert(std::is_same<BitmaskField_3bytes::value_type, std::uint32_t>::value, "std::uint32_t type is expected");
/// assert(BitmaskField_2bytes().length() == 3U);
///
/// using BitmaskField_4bytes = nil::marshalling::types::BitmaskValue<MyFieldBase, nil::marshalling::option::fixed_length<4> >;
/// static_assert(std::is_same<BitmaskField_4bytes::value_type, std::uint32_t>::value, "std::uint32_t type is expected");
/// assert(BitmaskField_2bytes().length() == 4U);
/// @endcode
/// All the @ref sec_field_tutorial_common_options can also be used with 
/// nil::marshalling::types::BitmaskValue.
///
/// @subsection sec_field_tutorial_bitmask_value_reserved Reserved Bits
/// Quite often the bitmask fields contain reserved bits, which must preserve
/// some values (usually 0). The nil::marshalling::types::BitmaskValue fields support
/// usage of nil::marshalling::option::bitmask_reserved_bits alias option. The template
/// parameters of the option specify mask for reserved bits as well as their
/// expected values. The check for the reserved bits values is performed inside
/// @b nil::marshalling::types::BitmaskValue::valid() member function.
/// @code
/// using MyBitmask = 
///     nil::marshalling::types::BitmaskValue<
///         MyFieldBase, 
///         nil::marshalling::option::fixed_length<1>,
///         nil::marshalling::option::bitmask_reserved_bits<0x2, 0> // Second bit is reserved and must be 0
///     >;
/// @endcode
///
/// @subsection sec_field_tutorial_bitmask_value_names Bit Names
/// Quite often there is a need to provide names for the bits in the 
/// nil::marshalling::types::BitmaskValue field. It is possible to define it as external
/// independent enum. However, it may be convenient to define it as internal
/// type. It is possible to do by inheriting from appropriate nil::marshalling::types::BitmaskValue
/// type and use MARSHALLING_BITMASK_BITS() macro to define names for bits. For example
/// @code
/// struct MyBitmask : public
///     nil::marshalling::types::BitmaskValue<
///         MyFieldBase, 
///         nil::marshalling::option::fixed_length<1>,
///         nil::marshalling::option::bitmask_reserved_bits<0x2, 0> // Second bit is reserved and must be 0
///     >
/// {
///     MARSHALLING_BITMASK_BITS(first, third=2, fourth, fifth, sixth, seventh, eighth);
/// }
/// @endcode
/// is equivalent to defining:
/// @code
/// struct MyBitmask : public
///     nil::marshalling::types::BitmaskValue<
///         MyFieldBase, 
///         nil::marshalling::option::fixed_length<1>,
///         nil::marshalling::option::bitmask_reserved_bits<0x2, 0>
///     >
/// {
///     enum BitIdx
///     {
///         BitIdx_first,
///         BitIdx_third=2,
///         BitIdx_fourth,
///         BitIdx_fifth,
///         BitIdx_sixth,
///         BitIdx_seventh,
///         BitIdx_eighth,
///         BitIdx_numOfValues,
///     }
/// }
/// @endcode
/// @b NOTE, that provided names have found their way to @b BitIdx enum type, and
/// got prefixed with @b BitIdx_. This indices may be used with 
/// nil::marshalling::types::BitmaskValue::get_bit_value() and nil::marshalling::types::BitmaskValue::set_bit_value()
/// member functions.
///
/// Also note, that there is automatically generated @b BitIdx_numOfValues 
/// value to indicate end of the names list.
///
/// Due to the fact that the provided bit names may have @b =val suffixes, it
/// excludes the ability to generate proper access functions for the named bits.
/// However, the @b Marshalling library also provides @ref MARSHALLING_BITMASK_BITS_ACCESS()
/// macro, which can be used in addition to @ref MARSHALLING_BITMASK_BITS() one to
/// generate the convenience functions. For example:
/// @code
/// struct MyBitmask : public
///     nil::marshalling::types::BitmaskValue<
///         MyFieldBase, 
///         nil::marshalling::option::fixed_length<1>,
///         nil::marshalling::option::bitmask_reserved_bits<0x2, 0> // Second bit is reserved and must be 0
///     >
/// {
///     MARSHALLING_BITMASK_BITS(first, third=2, fourth, fifth, sixth, seventh, eighth);
///     MARSHALLING_BITMASK_BITS_ACCESS(first, third, fourth, fifth, sixth, seventh, eighth);
/// }
/// @endcode
/// is equivalent to defining:
/// @code
/// struct MyBitmask : public
///     nil::marshalling::types::BitmaskValue<
///         MyFieldBase, 
///         nil::marshalling::option::fixed_length<1>,
///         nil::marshalling::option::bitmask_reserved_bits<0x2, 0>
///     >
/// {
///     enum BitIdx {...}
///
///     bool getBitValue_first() const { return get_bit_value(BitIdx_first); }
///     void set_bit_value_first(bool val) { set_bit_value(BitIdx_first, val); }
///     bool getBitValue_third() const { ... }
///     void set_bit_value_third(bool val) { ... }
///     bool getBitValue_fourth() const { ... }
///     void set_bit_value_fourth(bool val) { ... }
///     ...
/// }
/// @endcode
/// In case the bit names definition is sequential starting with index 0 and
/// going up without and gaps, i.e. no @b =val suffixes are used, the usage of
/// two separate @ref MARSHALLING_BITMASK_BITS() and @ref MARSHALLING_BITMASK_BITS_ACCESS() macros,
/// can be unified into one @ref MARSHALLING_BITMASK_BITS_SEQ():
/// @code
/// struct MyBitmask : public
///     nil::marshalling::types::BitmaskValue<
///         MyFieldBase, 
///         nil::marshalling::option::fixed_length<1>,
///         nil::marshalling::option::bitmask_reserved_bits<0xf0, 0> // 4 MSBs are reserved
///     >
/// {
///     MARSHALLING_BITMASK_BITS_SEQ(first, second, third, fourth);
/// }
/// @endcode
/// <b style="color:red">WARNING:</b> Some compilers, such as @b clang or earlier
/// versions of @b gcc (v4.9 and earlier) may have problems compiling the 
/// @ref MARSHALLING_BITMASK_BITS_ACCESS() and @ref MARSHALLING_BITMASK_BITS_SEQ() macros
/// even though they contain valid C++11 code. If the compilation failure 
/// happens and the bitmask definition class is @b NOT a template one (like
/// in the example above), then try to substitute the used macros with
/// @ref MARSHALLING_BITMASK_BITS_ACCESS_NOTEMPLATE() and @ref MARSHALLING_BITMASK_BITS_SEQ_NOTEMPLATE()
/// respectively. For example:
/// @code
/// struct MyBitmask : public
///     nil::marshalling::types::BitmaskValue<
///         MyFieldBase, 
///         nil::marshalling::option::fixed_length<1>,
///         nil::marshalling::option::bitmask_reserved_bits<0xf0, 0> // 4 MSBs are reserved
///     >
/// {
///     MARSHALLING_BITMASK_BITS_SEQ_NOTEMPLATE(first, second, third, fourth);
/// }
/// @endcode
/// However, when the defined bitmask class is a template, then the inner
/// definition of @b Base type, which specifies the exact type of the base
/// class, is required. For example:
/// @code
/// template <typename... TExtraOptions>
/// class MyBitmask : public
///     nil::marshalling::types::BitmaskValue<
///         MyFieldBase, 
///         nil::marshalling::option::fixed_length<1>,
///         nil::marshalling::option::bitmask_reserved_bits<0xf0, 0>, // 4 MSBs are reserved
///         TExtraOptions...
///     >
/// {
///     // Duplicate base class type
///     using Base = 
///         nil::marshalling::types::BitmaskValue<
///             MyFieldBase, 
///             nil::marshalling::option::fixed_length<1>,
///             nil::marshalling::option::bitmask_reserved_bits<0xf0, 0>, // 4 MSBs are reserved
///             TExtraOptions...
///         >;
/// public:
///     MARSHALLING_BITMASK_BITS_SEQ(first, second, third, fourth);
/// }
/// @endcode
/// The same goes for MARSHALLING_BITMASK_BITS_ACCESS() macro.
///
/// @b NOTE, that @b Marshalling library also defines @b MARSHALLING_MUST_DEFINE_BASE in
/// case the base class definition is needed (going to be used). If the developed
/// application is going to be multi-platform and compiled with various compilers
/// (some of which may warn about unused private type) it is possible to use 
/// the defined symbol to add / remove the definition of the @b Base member type.
/// @code
/// template <typename... TExtraOptions>
/// class MyBitmask : public nil::marshalling::types::BitmaskValue<...>
/// {
/// #ifdef MARSHALLING_MUST_DEFINE_BASE
///     using Base = ...;
/// #endif
/// public:
///     MARSHALLING_BITMASK_BITS_SEQ(first, second, third, fourth);
/// }
/// @endcode
///
/// @section sec_field_tutorial_bitfield Bitfield fields_type
/// Many communication protocols try to pack multiple independent values into
/// a one or several bytes to save traffic on I/O link. For example, to encode
/// baud rate from example in @ref sec_field_tutorial_enum_value section, only 
/// 3 bits are needed (values [0 - 6]). The serial port configuration may
/// also require parity information, which may have only "None", "Even", and "Odd"
/// values:
/// |Parity    | Serialisation value|
/// |:--------:|:------------------:|
/// | None     | 0                  |
/// | Odd      | 1                  |
/// | Even     | 2                  |
///
/// @code
/// enum Parity : std::uint8_t
/// {
///     Parity_None,
///     Parity_Odd,
///     Parity_Even
/// };
/// @endcode
/// To encode parity value only 2 bits are needed. Together with the baud mentioned
/// earlier, these two values will consume only 5 bits. Let's also use
/// the remaining 3 bits to complete a single byte as some kind of flags.
///
/// | value    | Number of bits |
/// |:--------:|:--------------:|
/// | Baud     | 3              |
/// | Parity   | 2              |
/// | Flags    | 3              |
///
/// These value must be accessed and treated as independent values. However, they
/// must be bundled into a single byte when serialization happens. The
/// Marshalling library provides nil::marshalling::types::Bitfield field for this purpose.
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using SerialConfigField = 
///     nil::marshalling::types::Bitfield<
///         MyFieldBase, 
///         std::tuple<
///             nil::marshalling::types::EnumValue<MyFieldBase, Baud, nil::marshalling::option::fixed_bit_length<3> >,
///             nil::marshalling::types::EnumValue<MyFieldBase, Parity, nil::marshalling::option::fixed_bit_length<2> >,
///             nil::marshalling::types::BitmaskValue<MyFieldBase, nil::marshalling::option::fixed_bit_length<3> >
///         >
///     >;
/// @endcode
/// Please pay attention to the following detail:
/// @li The bitfield members are bundled in 
///     <a href="http://en.cppreference.com/w/cpp/utility/tuple">std::tuple</a>
///     and passed as the second template parameter.
/// @li The serialization length of every bitfield member is specified in bits using
///     nil::marshalling::option::fixed_bit_length (note difference to nil::marshalling::option::fixed_length
///     that specifies length in bytes).
/// @li The summary of all the "bit" lengths of all the members must be divisible
///     by 8, i.e. to be packed in any number of bytes without leaving a single
///     bit undefined.
/// @li The member of the bitfield may be any numeric field (nil::marshalling::types::IntValue,
///     nil::marshalling::types::EnumValue, and nil::marshalling::types::BitmaskValue), that support
///     nil::marshalling::option::fixed_bit_length option.
/// 
/// Every member of the bitfield may use all the supported options. The 
/// nil::marshalling::types::Bitfield itself may receive only options listed in its class
/// description.
///
/// To get an access to the member fields use @b value() member function:
/// @code
/// SerialConfigField serialConfigField;
/// ...
/// auto& members = serialConfigField.value(); // reference to the stored tuple of field members
/// auto& buadField = std::get<0>(members); // reference to the baud field;
/// auto& parityField = std::get<1>(members); // reference to the parity field;
/// auto& flagsField = std::get<2>(members); // reference to the flags field
///
/// baudField.value() = Baud_115200; // =6
/// parityField.value() = Parity_Even; // =2
/// flagsField.value() = 0x2;
/// 
/// std::vector<std::uint8_t> outData; // Pretend output buffer
/// auto writeIter = std::back_inserter(outData);
/// auto es = baud.write(writeIter, outData.max_size());
/// assert(es == nil::marshalling::ErrorStatus::success); // No error is expected
/// assert(outData.size() == 1); // Single byte output is expected
/// assert(outData[0] == 0x56); // Binary value split to 3-2-3 bits: 010|10|110
/// @endcode
///
/// It would be convenient to access the member fields by name, rather than
/// by index with <a href="http://en.cppreference.com/w/cpp/utility/tuple/get">std::get</a>.
/// It can be achieved by using
/// MARSHALLING_FIELD_MEMBERS_ACCESS() macro inside field definition class.
/// @code
/// class SerialConfigField : public nil::marshalling::types::Bitfield<...>
/// {
/// public:
///     MARSHALLING_FIELD_MEMBERS_ACCESS(baud, parity, flags);
/// }
/// @endcode
/// It is equivalent to having the following enum, types and functions defined:
/// @code
/// class SerialConfigField : public nil::marshalling::types::Bitfield<...>
/// {
/// public:
///     // Access indices for member fields
///     enum FieldIdx {
///         FieldIdx_baud,
///         FieldIdx_parity,
///         FieldIdx_flags,
///         FieldIdx_numOfValues
///     };
/// 
///     // Accessor to "baud" field
///     auto field_baud() -> decltype(std::get<FieldIdx_baud>(value()))
///     {
///         return std::get<FieldIdx_baud>(value());
///     }
///
///     // Accessor to const "baud" field
///     auto field_baud() const -> decltype(std::get<FieldIdx_baud>(value()))
///     {
///         return std::get<FieldIdx_baud>(value());
///     }
///
///     // Accessor to "parity" field
///     auto field_parity() -> decltype(std::get<FieldIdx_parity>(value()))
///     {
///         return std::get<FieldIdx_parity>(value());
///     }
///
///     // Accessor to const "parity" field
///     auto field_parity() const -> decltype(std::get<FieldIdx_parity>(value()))
///     {
///         return std::get<FieldIdx_parity>(value());
///     }
///
///     // Accessor to "flags" field
///     auto field_flags() -> decltype(std::get<FieldIdx_flags>(value()))
///     {
///         return std::get<FieldIdx_flags>(value());
///     }
///
///     // Accessor to const "flags" field
///     auto field_flags() const -> decltype(std::get<FieldIdx_flags>(value()))
///     {
///         return std::get<FieldIdx_flags>(value());
///     }
/// };
/// @endcode
/// @b NOTE, that provided names @b baud, @b parity, and @b flags, have
/// found their way to the following definitions:
/// @li @b FieldIdx enum. The names are prefixed with @b FieldIdx_. The
///     @b FieldIdx_nameOfValues value is automatically added at the end.
/// @li Accessor functions prefixed with @b field_
///
/// As the result, the fields can be accessed using multiple ways:
/// For example using @b FieldIdx enum
/// @code
/// SerialConfigField field;
/// auto& members = field.value(); // get access to the std::tuple of member fields
/// auto& baudField = std::get<SerialConfigField::FieldIdx_baud>(members);
/// auto& parityField = std::get<SerialConfigField::FieldIdx_parity>(members);
/// auto& flagsField = std::get<SerialConfigField::FieldIdx_flags>(members);
///
/// auto baud = baudField.value();
/// auto parity = parityField.value();
/// auto flags = flagsField.value();
/// @endcode
/// or using accessor functions:
/// @code
/// SerialConfigField field;
/// auto baud = field.field_baud().value();
/// auto parity = field.field_parity().value();
/// auto flags = field.flags.value();
/// @endcode
/// <b style="color:red">WARNING:</b> Some compilers, such as @b clang or earlier
/// versions of @b gcc (v4.9 and earlier) may have problems compiling the 
/// @ref MARSHALLING_FIELD_MEMBERS_ACCESS() macro
/// even though it contains valid C++11 code. If the compilation failure 
/// happens and the bitfield definition class is @b NOT a template one (like
/// in the example above), then try to substitute the used macro with
/// @ref MARSHALLING_FIELD_MEMBERS_ACCESS_NOTEMPLATE(). For example:
/// @code
/// class SerialConfigField : public nil::marshalling::types::Bitfield<...>
/// {
/// public:
///     MARSHALLING_FIELD_MEMBERS_ACCESS_NOTEMPLATE(baud, parity, flags);
/// }
/// @endcode
/// However, when the defined bitfield class is a template, then the inner
/// definition of @b Base type, which specifies the exact type of the base
/// class, is required. For example:
/// @code
/// template <typename... TExtraOptions>
/// class MyBitfieldField : public 
///     nil::marshalling::types::Bitfield<
///         MyFieldBase, 
///         std::tuple<SomeField1, SomeField2, SomeField3>,
///         TExtraOptions...
///     >
/// {
///     // Duplicate the base class type
///     using Base = 
///         nil::marshalling::types::Bitfield<
///             MyFieldBase, 
///             std::tuple<SomeField1, SomeField2, SomeField3>,
///             TExtraOptions...
///         >;
/// public:
///     MARSHALLING_FIELD_MEMBERS_ACCESS(member1, member2, member3);
/// }
/// @endcode
/// @b NOTE, that @b Marshalling library also defines @b MARSHALLING_MUST_DEFINE_BASE in
/// case the base class definition is needed (going to be used). If the developed
/// application is going to be multi-platform and compiled with various compilers
/// (some of which may warn about unused private type) it is possible to use 
/// the defined symbol to add / remove the definition of the @b Base member type.
/// @code
/// template <typename... TExtraOptions>
/// class MyBitfieldField : public nil::marshalling::types::Bitfield<...>
/// {
/// #ifdef MARSHALLING_MUST_DEFINE_BASE
///     using Base = ...;
/// #endif
/// public:
///     MARSHALLING_FIELD_MEMBERS_ACCESS(member1, member2, member3);
/// }
/// @endcode
///     
/// @section sec_field_tutorial_bundle Bundle fields_type
/// There are cases when multiple independent fields need to be bundled into
/// a single field and expose the required interface of reading, writing,
/// calculating length, checking field's contents validity, and bringing field's
/// value into a consistent state. It may be required
/// when a message contains sequence (see @ref sec_field_tutorial_array_list) 
/// of such bundles/structs. The Marshalling library provides nil::marshalling::types::Bundle
/// field for this purpose. It is quite similar to nil::marshalling::types::Bitfield described
/// earlier. The difference is that every member field
/// doesn't specify any length in bits, just bytes. For example:
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
///
/// enum SomeEnum : std::uint8_t
/// {
///     SomeEnum_Value1,
///     SomeEnum_Value2,
///     SomeEnum_Value3,
///     ...
/// }
///
/// using MyBundle =
///     nil::marshalling::types::Bundle<
///         MyFieldBase,
///         std::tuple<
///             nil::marshalling::types::IntValue<MyFieldBase, std::int16_t> // 2 bytes int value
///             nil::marshalling::types::EnumValue<MyFieldBase, SomeEnum>, // 1 byte enum value
///             nil::marshalling::types::BitmaskValue<MyFieldBase, nil::marshalling::option::fixed_length<1> > // 1 byte bitmask
///         >
///     >;
///
/// MyBundle bundleField;
/// ...
/// auto& members = bundleField.value(); // reference to the stored tuple of field members
/// auto& intValueField = std::get<0>(members);
/// auto& enumValueField = std::get<1>(members);
/// auto& bitmaskValueField = std::get<2>(members);
///
/// intValueField.value() = ...; // access the value of IntValue member field.
/// enumValueField.value() = ...; // access the value of EnumValue member field.
/// bitmaskValueField.value() = ...; // access the value of BitmaskValue member field.
///
/// std::vector<std::uint8_t> outData; // Pretend output buffer
/// auto writeIter = std::back_inserter(outData);
/// auto es = baud.write(writeIter, outData.max_size());
/// assert(es == nil::marshalling::ErrorStatus::success); // No error is expected
/// assert(outData.size() == 4); // Expected 2 bytes for IntValue, 1 byte for EnumValue and 1 byte for BitmaskValue
/// @endcode 
/// The default behaviour of nil::marshalling::types::Bundle may be extended with options.
/// Please refer to the class documentation for the list of supported options.
///
/// Just like with the @ref sec_field_tutorial_bitfield, the names to the
/// member fields can be provided by using MARSHALLING_FIELD_MEMBERS_ACCESS() macro.
/// @code
/// class MyBundle : public nil::marshalling::types::Bundle<...>
/// {
/// public:
///     MARSHALLING_FIELD_MEMBERS_ACCESS(member1, member2, member3);
/// };
/// @endcode
/// It will create similar enum and convenience access functions, just
/// like described in previous @ref sec_field_tutorial_bitfield section.
///
/// <b style="color:red">WARNING:</b> Due to the fact that the same
/// @ref MARSHALLING_FIELD_MEMBERS_ACCESS() macro is used as with
/// the @ref sec_field_tutorial_bitfield, the same warning applies.
/// If compilation fails on the attempt to compile MARSHALLING_FIELD_MEMBERS_ACCESS(),
/// use either MARSHALLING_FIELD_MEMBERS_ACCESS_NOTEMPLATE() alternative or define
/// inner @b Base type to specify actual type of @ref nil::marshalling::types::Bundle
/// type. For example:
/// @code
/// template <typename... TExtraOptions>
/// class MyBundle : public
///     nil::marshalling::types::Bundle<
///         MyFieldBase,
///         std::tuple<SomeField1, SomeField2, SomeField3>,
///         TExtraOptions...
///     >
/// {
///     // Duplicate base type definition
///     using Base =
///         nil::marshalling::types::Bundle<
///             MyFieldBase,
///             std::tuple<SomeField1, SomeField2, SomeField3>,
///             TExtraOptions...
///         >;
/// public:
///     MARSHALLING_FIELD_MEMBERS_ACCESS(member1, member2, member3);
/// };
/// @endcode
/// @b NOTE, that @b Marshalling library also defines @b MARSHALLING_MUST_DEFINE_BASE in
/// case the base class definition is needed (going to be used). If the developed
/// application is going to be multi-platform and compiled with various compilers
/// (some of which may warn about unused private type) it is possible to use 
/// the defined symbol to add / remove the definition of the @b Base member type.
/// @code
/// template <typename... TExtraOptions>
/// class MyBundle : public nil::marshalling::types::Bundle<...>
/// {
/// #ifdef MARSHALLING_MUST_DEFINE_BASE
///     using Base = ...;
/// #endif
/// public:
///     MARSHALLING_FIELD_MEMBERS_ACCESS(member1, member2, member3);
/// };
/// @endcode
///
/// @section sec_field_tutorial_array_list Array List fields_type
/// Some communication protocols may define messages that transmit sequence
/// of similar fields and/or raw data buffers. To make it easier to handle, the
/// Marshalling library provides nil::marshalling::types::array_list field which provide a required
/// interface to properly handle such sequences of data. It supports a
/// sequence of raw bytes
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using MySimpleList = 
///     nil::marshalling::types::array_list<
///         MyFieldBase,
///         std::uint8_t
///     >;
/// @endcode
/// as well as using sequence of any fields defined in nil::marshalling::field namespace
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using MyComplexList = 
///     nil::marshalling::types::array_list<
///         MyFieldBase,
///         MyBundle<> // Complex bundle field, defined in previous section 
///     >;
/// @endcode
/// By default the read operation on nil::marshalling::types::array_list continues as
/// long as there is data left in input buffer, and write operation serialises
/// all the data stored in internal vector. These default behaviours can be 
/// changed using options described below.
///
/// @subsection sec_field_tutorial_array_list_size_prefix Prefixing with Size Information
/// Very often variable size sequences of raw bytes or other fields get
/// prefixed with size information. The default behaviour of the 
/// nil::marshalling::types::array_list is to read until the end of the buffer. Having
/// sequence prefixed with number of elements to follow, allows earlier
/// termination of the read operation, and allows having other independent
/// fields to be appended after the sequence. The nil::marshalling::types::array_list
/// class supports nil::marshalling::option::sequence_size_field_prefix option that allows
/// to specify type of the size field (usually a variant of nil::marshalling::types::IntValue)
/// to be serialized before the contents of nil::marshalling::types::array_list being
/// serialized. For example, the serialized raw bytes sequence is prefixed with
/// 2 bytes of size information: 
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
///
/// using SizePrefixField = nil::marshalling::types::IntValue<MyFieldBase, std::uint16_t>;
///
/// using MyList = 
///     nil::marshalling::types::array_list<
///         MyFieldBase,
///         std::uint8_t,
///         nil::marshalling::option::sequence_size_field_prefix<SizePrefixField>
///     >;
///
/// static const std::uint8_t InputBuffer[] = {
///     0x0, 0x3, 0xa, 0xb, 0xc, 0xd, 0xe, 0xf
/// }
/// static const auto InputBufferSize = std::extent<decltype(InputBuffer)>::value;
///
/// MyList myList;
/// const auto* readIter = &InputBuffer[0];
/// auto es = myList.read(readIter, InputBufferSize); 
/// assert(es == nil::marshalling::ErrorStatus::success); // No error is expected;
/// assert(myList.value().size() == 3U); // Reading only 3 elements
/// assert((myList.value())[0] == 0xa); // First element
/// assert((myList.value())[1] == 0xb); // Second element 
/// assert((myList.value())[2] == 0xc); // Third element
/// assert(std::distance(&InputBuffer[0], readIter) == 5); // Expected to consume 2 first bytes of the size + ,
///                                                        // number of elements size specified (=3). Overall 5 bytes consumed 
///
///
/// std::vector<std::uint8_t> outputBuffer;
/// auto writeIter = std::back_inserter(outputBuffer);
/// es = myList.write(writeIter, outputBuffer.max_size());
/// assert(es == nil::marshalling::ErrorStatus::success); // No error is expected;
/// assert(outputBuffer.size() == 5U); // Expected to write 5 bytes, 2 bytes for size, and 3 for elements.
/// assert(std::equal(outputBuffer.begin(), outputBuffer.end(), std::begin(InputBuffer)); // The output must be equal to
/// @endcode
/// 
/// Some protocols prefix the sequence with <b>serialization length</b> rather
/// than <b>number of elements to follow</b>. In this case the 
/// @ref nil::marshalling::option::sequence_ser_length_field_prefix option needs to be used
/// instead of @ref nil::marshalling::option::sequence_size_field_prefix.
///
/// @subsection sec_field_tutorial_array_list_elem_length_prefix Element Serialisation length Prefix
/// Also some protocols, for easier exchange of lists between nodes that use 
/// different versions of the same protocol, may require prefixing <b>every
/// element</b> of the list with its serialization length. In this case
/// @ref nil::marshalling::option::sequence_elem_ser_length_field_prefix option may be used.
/// For example, the list of bundles prefixed with 2 bytes specifying number of
/// elements to follow, and with every element prefixed with its serialization length using
/// variable length base-128 encoding may look like this:
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
///
/// using SizePrefixField = nil::marshalling::types::IntValue<MyFieldBase, std::uint16_t>;
/// using ElemLengthPrefixField = 
///     nil::marshalling::types::IntValue<
///         MyFieldBase, 
///         std::uint32_t,
///         nil::marshalling::option::var_length<1, 4> // variable length encoding up to 4 bytes
///     >;
///
/// using MyList = 
///     nil::marshalling::types::array_list<
///         MyFieldBase,
///         MyBundle, // some bundle of fields
///         nil::marshalling::option::sequence_size_field_prefix<SizePrefixField>,
///         nil::marshalling::option::sequence_elem_ser_length_field_prefix<ElemLengthPrefixField>
///     >;
/// @endcode
/// When every element of the list is of fixed size, i.e. has the same serialization
/// length, it becomes redundant to prefix @b every element with its length.
/// Instead, only first element can be prefixed with one, and all others may 
/// reuse the same information. To achieve such behaviour 
/// @ref nil::marshalling::option::sequence_elem_fixed_ser_length_field_prefix should be used instead.
/// For example, the list of <b>fixed length</b> bundles prefixed with 1 byte specifying number of
/// elements to follow, and with first element prefixed with 1 byte containing its serialization length
/// may look like this:
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
///
/// using SizePrefixField = nil::marshalling::types::IntValue<MyFieldBase, std::uint8_t>;
/// using ElemLengthPrefixField = nil::marshalling::types::IntValue<MyFieldBase, std::uint8_t>;
///
/// using MyList = 
///     nil::marshalling::types::array_list<
///         MyFieldBase,
///         nil::marshalling::types::Bundle<
///             MyFieldBase,
///             std::tuple<
///                 nil::marshalling::types::IntValue<MyFieldBase, std::uint16_t>,
///                 nil::marshalling::types::IntValue<MyFieldBase, std::uint8_t>
///             >
///         >,
///         nil::marshalling::option::sequence_size_field_prefix<SizePrefixField>,
///         nil::marshalling::option::sequence_elem_fixed_ser_length_field_prefix<ElemLengthPrefixField>
///     >;
/// @endcode
///
/// @subsection sec_field_tutorial_array_list_detached_size_prefix Detached Size Information
/// There may be cases when size information is detached from the sequence itself, i.e.
/// there are other fields between the size field and the sequence itself. 
/// For example, the protocol specifies the following:
/// | Byte Offset | length | Description |
/// |:-----------:|:------:|:-----------:|
/// | 0           | 1      | Number of elements in sequence |
/// | 1           | 1      | Some flags bitmask | 
/// | 2           | 2 * N  | Sequence of 2 byte integral values |
///
/// In this case the option nil::marshalling::option::sequence_size_field_prefix can NOT
/// be used. In fact the size information is not a part of the sequence any
/// more, it must be a separate independent field. When this field
/// is successfully read, its value must be forced upon the sequence somehow
/// before the read operation of the sequence takes place. To help with such
/// forcing, nil::marshalling::option::sequence_size_forcing_enabled option was introduced.
/// When this option used, the nil::marshalling::types::array_list::force_read_elem_count member
/// function of the field may be used to force number of elements that follow.
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using SeqSizeField = nil::marshalling::types::IntValue<MyFieldBase, std::uint8_t>;
/// using BitmaskField = nil::marshalling::types::BitmaskValue<MyFieldBase, nil::marshalling::option::fixed_length<1> >;
/// using MyList = 
///     nil::marshalling::types::array_list<
///         MyFieldBase,
///         nil::marshalling::types::IntValue<MyFieldBase, std::uint16_t>,
///         nil::marshalling::option::sequence_size_forcing_enabled
///     >;
///
/// static const std::uint8_t InputBuffer[] = {
///     0x3, 0xff, 0xa, 0xb, 0xc, 0xd, 0xe, 0xf
/// }
/// static const auto InputBufferSize = std::extent<decltype(InputBuffer)>::value;
///
/// const auto* readIter = &InputBuffer[0];
/// auto remSize = InputBufferSize;
///
/// SeqSizeField sizeField;
/// auto es = sizeField.read(readIter, remSize); 
/// assert(es == nil::marshalling::ErrorStatus::success); // No error is expected;
/// assert(sizeField.value() == 3U); // First byte should be read;
/// 
/// remSize -= sizeField.length();
/// BitmaskField bitmask;
/// es = bitmask.read(readIter, remSize);
/// assert(es == nil::marshalling::ErrorStatus::success); // No error is expected;
/// assert(bitmask.value() == 0xff); // Second byte should be read;
///
/// remSize -= bitmask.length();
/// MyList myList;
/// myList.force_read_elem_count(sizeField.value()); // Force number of elements to read
/// es = myList.read(readIter, remSize);
/// assert(es == nil::marshalling::ErrorStatus::success); // No error is expected;
/// assert(myList.value().size() == 3U); // Reading only 3 elements
/// assert((myList.value())[0] == 0xa); // First element
/// assert((myList.value())[1] == 0xb); // Second element 
/// assert((myList.value())[2] == 0xc); // Third element
/// @endcode
///
/// @subsection sec_field_tutorial_array_list_force_element_size Forcing Element Serialisation length
/// In addition to prefixing variable length lists with amount of elements to
/// follow, some protocols may also prefix them with serialization
/// length of the <b>single element</b>. Such technique is usually used to
/// maintain data exchange compatibility with earlier versions of the protocol,
/// which may be used on the other side of the communication link. The @b Marshalling
/// library allows forcing the serialization length of a single element when
/// such information becomes available. It is similar to 
/// @ref sec_field_tutorial_array_list_detached_size_prefix. The option
/// @ref nil::marshalling::option::sequence_elem_length_forcing_enabled needs to be used when
/// defining the field type, and @ref nil::marshalling::types::array_list::force_read_elem_length()
/// and @ref nil::marshalling::types::array_list::clear_read_elem_length_forcing() functions to
/// set/clear the forcing information.
/// @code
/// // Common base class for all the fields
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
///
/// // field_type used to serialise serialization length of a single element in the list
/// using ElemLengthPrefixField = nil::marshalling::types::IntValue<MyFieldBase, std::uint8_t>;
/// 
/// // field_type used to serialise number of elements in the list
/// using SizePrefixField = nil::marshalling::types::IntValue<MyFieldBase, std::uint8_t>;
///
/// using MyList = 
///     nil::marshalling::types::array_list<
///         MyFieldBase,
///         nil::marshalling::types::IntValue< // 3 bytes integers
///             MyFieldBas, 
///             std::uint32_t, 
///             nil::marshalling::option::fixed_length<3> >,
///         nil::marshalling::option::sequence_size_field_prefix<SizePrefixField>, // 1 byte prefix
///         nil::marshalling::option::sequence_elem_length_forcing_enabled // enable forcing of the element length
///     >;
///
/// static const std::uint8_t InputBuffer[] = {
///     0x4, // single element serialization length
///     0x2, // number of elements in the list,
///     0xa, 0xa, 0xa, 0x0, // first element + padding 
///     0xb, 0xb, 0xb, 0x0 // second element + padding
/// }
/// static const auto InputBufferSize = std::extent<decltype(InputBuffer)>::value;
///
/// ElemLengthPrefixField lengthPrefix;
/// MyList myList;
/// const auto* readIter = &InputBuffer[0];
/// auto es = lengthPrefix(readIter, InputBufferSize);
/// assert(es == nil::marshalling::ErrorStatus::success); // No error is expected;
/// assert(lengthPrefix.value() == 4U);
///
/// myList.force_read_elem_length(lengthPrefix.value()); // force serialization length of the single element
/// auto es = myList.read(readIter, InputBufferSize - lengthPrefix.length()); 
/// assert(es == nil::marshalling::ErrorStatus::success); // No error is expected;
/// assert(myList.value().size() == 2U); // Reading only 2 elements
/// assert((myList.value())[0] == 0x0a0a0a); // First element
/// assert((myList.value())[1] == 0x0b0b0b); // Second element 
/// assert(std::distance(&InputBuffer[0], readIter) == 10); // Expected to consume in the
/// @endcode
///
/// @subsection sec_field_tutorial_array_list_term_suffix Terminating Sequence with Suffix
/// Sometimes there is no information about size of the sequence up front. It
/// may be terminating using some kind of special value. For example, the
/// sequence of raw bytes is terminated by the value of 0. Such termination
/// is achieved by using nil::marshalling::option::sequence_termination_field_suffix option.
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using TermField = nil::marshalling::types::IntValue<MyFieldBase, std::uint8_t>; // Default value is 0.
/// using MyList = 
///     nil::marshalling::types::array_list<
///         MyFieldBase,
///         nil::marshalling::types::IntValue<MyFieldBase, std::uint8_t>,
///         nil::marshalling::option::sequence_termination_field_suffix<TermField>
///     >;
///
/// static const std::uint8_t InputBuffer[] = {
///     0x1, 0x2, 0x3, 0x4, 0x0, 0xa, 0xb, 0xc
/// }
/// static const auto InputBufferSize = std::extent<decltype(InputBuffer)>::value;
///
/// const auto* readIter = &InputBuffer[0];
///
/// MyList myList;
/// es = myList.read(readIter, InputBufferSize);
/// assert(es == nil::marshalling::ErrorStatus::success); // No error is expected;
/// assert(myList.value().size() == 4U); // Reading only 4 elements, terminating 0 is not included
/// assert((myList.value())[0] == 0x1); // First element
/// assert((myList.value())[1] == 0x2); // Second element 
/// assert((myList.value())[2] == 0x3); // Third element
/// assert((myList.value())[4] == 0x4); // Fourth element
/// assert(std::distance(&InputBuffer[0], readIter) == 5); // Expected to consume all bytes including termination one 
/// @endcode
///
/// @subsection sec_field_tutorial_array_list_fixed_size Fixed Size Sequences
/// In many cases the size of the sequence is defined in the protocol without
/// any prefix or suffix to define the length of the sequence. To define
/// such sequence nil::marshalling::option::sequence_fixed_size option should be used.
/// Below is example of how to define sequence of four unsigned 16 bit integer
/// values.
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using MyList = 
///     nil::marshalling::types::array_list<
///         MyFieldBase,
///         nil::marshalling::types::IntValue<MyFieldBase, std::uint16_t>,
///         nil::marshalling::option::sequence_fixed_size<4>
///     >;
///
/// static const std::uint8_t InputBuffer[] = {
///     0x0, 0x1, 0x0, 0x2, 0x0, 0x3, 0x0, 0x4, 0xa, 0xb, 0xc
/// }
/// static const auto InputBufferSize = std::extent<decltype(InputBuffer)>::value;
///
/// const auto* readIter = &InputBuffer[0];
///
/// MyList myList;
/// es = myList.read(readIter, InputBufferSize);
/// assert(es == nil::marshalling::ErrorStatus::success); // No error is expected;
/// assert(myList.value().size() == 4U); // Reading only 4 elements
/// assert((myList.value())[0] == 0x1); // First element
/// assert((myList.value())[1] == 0x2); // Second element 
/// assert((myList.value())[2] == 0x3); // Third element
/// assert((myList.value())[4] == 0x4); // Fourth element
/// assert(std::distance(&InputBuffer[0], readIter) == 8); // Consumed only 4 element (2 bytes each) 
/// @endcode
/// @b NOTE, that nil::marshalling::option::sequence_fixed_size option insures existence of
/// the right number of elements "on the wire", but doesn't influence number
/// of elements in the newly created list field:
/// @code
/// MyList myList;
/// auto& storageVector = myList.value();
/// assert(storageVector.empty());
/// @endcode
/// Also nothing prevents from having too many values in the storage vector, but
/// only specified number of the elements will be serialized:
/// @code
/// myList.push_back(0x1); // will be serialized
/// myList.push_back(0x2); // will be serialized
/// myList.push_back(0x3); // will be serialized
/// myList.push_back(0x4); // will be serialized
/// myList.push_back(0x5); // WON'T be serialized
/// @endcode
///
/// @subsection sec_field_tutorial_array_list_storage value Storage
/// By default, the internal data is stored using 
/// <a href="http://en.cppreference.com/w/cpp/container/vector">std::vector</a>.
/// @code
/// MySimpleList simpleList; // defined above
/// auto& simpleListStorage = simpleList.value(); // reference to std::vector<std::uint8_t>;
///
/// MyComplexList complexList; // defined above
/// auto& complexListStorage = complexList.value(); // reference to std::vector<MyBundle>;
/// @endcode
/// This behaviour can be modified using extra options such as @ref
/// nil::marshalling::option::custom_storage_type, @ref nil::marshalling::option::fixed_size_storage,
/// @ref nil::marshalling::option::orig_data_view, or @ref nil::marshalling::option::sequence_fixed_size_use_fixed_size_storage.
/// @b HOWEVER, these options do not influence the way how list fields are being
/// serialized, they influence the way how list value has been stored. As the result,
/// they should @b NOT be used in protocol definition. Instead, provide a way to
/// to the actual application to modify the default storage by passing extra
/// options. For example:
/// @code
/// template <typename... TExtraOptions>
/// using MyList = nil::marshalling::types::array_list<..., TExtraOptions...>;
/// @endcode
/// 
/// All the @ref sec_field_tutorial_common_options are also applicable to
/// nil::marshalling::types::array_list field.
///
/// @section sec_field_tutorial_string String fields_type
/// Many protocols have to transfer strings. They are defined using
/// @ref nil::marshalling::types::String field.
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using MyString = nil::marshalling::types::String<MyFieldBase>;
/// @endcode
/// It is very similar to nil::marshalling::types::array_list
/// it terms of value storage, read/write operations, and supported options.
/// By default the value is stored as 
/// <a href="http://en.cppreference.com/w/cpp/string/basic_string">std::string</a>.
/// @code
/// MyString myStr;
/// auto& myStrStorage = myStr.value(); // reference to std::string.
/// @endcode
/// Just like described in @ref sec_field_tutorial_array_list_storage section
/// above the same options can be used to modify the storage type of the 
/// nil::marshalling::types::String field, but should @b NOT be used in protocol definition, but
/// instead there should be an ability to provide extra options.
/// @code
/// template <typename... TExtraOptions>
/// using MyString = nil::marshalling::types::String<MyFieldBase, TExtraOptions...>;
/// @endcode
///
/// Prefixing string with single byte of the size information will look like this:
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using SizePrefixField = nil::marshalling::types::IntValue<MyFieldBase, std::uint8_t>;
/// using MyString = 
///     nil::marshalling::types::String<
///         MyFieldBase, 
///         nil::marshalling::option::sequence_size_field_prefix<SizePrefixField>
///     >;
///
/// MyString myStr;
/// myStr.value() = "hello";
///
/// std::vector<std::uint8_t> outputBuf;
/// auto writeIter = std::back_inserter(outputBuf);
/// auto es = myStr.write(writeIter, outputBuf.max_size());
/// assert(es = nil::marshalling::ErrorStatus::success); // No error is expected
/// assert(outputBuf.size() == 6U); // 1 byte of size, followed by 5 characters of "hello" string
/// assert(outputBuf[0] == 5U); // size info
/// assert(outputBuf[1] == 'h');
/// assert(outputBuf[2] == 'e');
/// assert(outputBuf[3] == 'l');
/// assert(outputBuf[4] == 'l');
/// assert(outputBuf[5] == 'o');
/// @endcode
/// See also @ref sec_field_tutorial_array_list_size_prefix.
///
/// Encoding of zero termination strings without size prefix can be defined like
/// this:
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using ZeroTermField = nil::marshalling::types::IntValue<MyFieldBase, std::uint8_t>; // default value is 0
/// using MyString = 
///     nil::marshalling::types::String<
///         MyFieldBase, 
///         nil::marshalling::option::sequence_termination_field_suffix<ZeroTermField>
///     >;
///
/// MyString myStr;
/// myStr.value() = "hello";
///
/// std::vector<std::uint8_t> outputBuf;
/// auto writeIter = std::back_inserter(outputBuf);
/// auto es = myStr.write(writeIter, outputBuf.max_size());
/// assert(es = nil::marshalling::ErrorStatus::success); // No error is expected
/// assert(outputBuf.size() == 6U); // 5 characters of "hello" string followed by zero termination suffix
/// assert(outputBuf[0] == 'h');
/// assert(outputBuf[1] == 'e');
/// assert(outputBuf[2] == 'l');
/// assert(outputBuf[3] == 'l');
/// assert(outputBuf[4] == 'o');
/// assert(outputBuf[5] == 0U);
/// @endcode
/// See also @ref sec_field_tutorial_array_list_term_suffix.
///
/// Another string example is to have zero terminated string, the serialization
/// of which occupies exactly 32 bytes, i.e. the string may have up to 31 non-zero
/// characters. If string is too short, the serialization data is padded by
/// zeros until full length of 32 characters is produced.
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using ZeroTermField = nil::marshalling::types::IntValue<MyFieldBase, std::uint8_t>; // default value is 0
/// using MyString = 
///     nil::marshalling::types::String<
///         MyFieldBase, 
///         nil::marshalling::option::sequence_fixed_size<31>,
///         nil::marshalling::option::sequence_trailing_field_suffix<ZeroTermField>
///     >;
///
/// MyString myStr;
/// myStr.value() = "hello";
///
/// std::vector<std::uint8_t> outputBuf;
/// auto writeIter = std::back_inserter(outputBuf);
/// auto es = myStr.write(writeIter, outputBuf.max_size());
/// assert(es = nil::marshalling::ErrorStatus::success); // No error is expected
/// assert(outputBuf.size() == 32); // 5 characters of "hello" string followed by zero padding
/// assert(outputBuf[0] == 'h');
/// assert(outputBuf[1] == 'e');
/// assert(outputBuf[2] == 'l');
/// assert(outputBuf[3] == 'l');
/// assert(outputBuf[4] == 'o');
/// assert(outputBuf[5] == 0U);
/// ...
/// assert(outputBuf[31] == 0U);  
/// @endcode
/// @b NOTE, that the example above uses nil::marshalling::option::sequence_trailing_field_suffix
/// option, rather than nil::marshalling::option::sequence_termination_field_suffix.
/// The options slightly differ. The "termination" one 
/// (nil::marshalling::option::sequence_termination_field_suffix) forces the field to
/// stop reading when termination value is encountered, while "trailing" one
/// (nil::marshalling::option::sequence_trailing_field_suffix) doesn't check what it reads,
/// the reading size must be limited by other means (nil::marshalling::option::sequence_fixed_size
/// in the example above). When the read is complete, it just consumes the
/// termination character. Both options, however, force the termination
/// character to be appended at the end during write operation. @n
/// <b>Also note</b>, that size limit is specified (using nil::marshalling::option::sequence_fixed_size)
/// to be 31. One more byte is added by the "trailing" suffix to complete to 32
/// bytes.
///
/// Just like with @ref nil::marshalling::types::array_list, it is possible to use static
/// storage for fixed size strings:
/// @code
/// using MyString = 
///     nil::marshalling::types::String<
///         ..., 
///         nil::marshalling::option::sequence_fixed_size<16>,
///         nil::marshalling::option::sequence_fixed_size_use_fixed_size_storage
///     >;
/// @endcode
/// or 
/// @code
/// using MyString = 
///     nil::marshalling::types::String<
///         ..., 
///         nil::marshalling::option::sequence_fixed_size<16>,
///         nil::marshalling::option::fixed_size_storage<16>
///     >;
/// @endcode
///
/// @section sec_field_tutorial_fp_value Floating Point value fields_type
/// Floating point value fields (nil::marshalling::types::FloatValue) are very similar to
/// @ref sec_field_tutorial_int_value, but use @b float or @b double as its 
/// internal storage type. They abstract the IEEE 754 floating point 
/// values, which are serialized "as is" with either big or little endian
/// encoding. The floating point value fields also support 
/// @ref sec_field_tutorial_int_value_units conversions.
///
/// @section sec_field_tutorial_optional Optional fields_type
/// Some protocols may define optional fields, which may exist or be missing
/// based on information recorded in other fields. For example there is a
/// "flags" bitmask field which specifies whether the following field exists or
/// missing. The optional field may also be tentative, i.e. if there is enough
/// data in the input buffer it exists, and missing otherwise. The Marshalling
/// library provides nil::marshalling::types::Optional which is a mere wrapper around
/// other fields and provides an ability to set the optional state of the field.
/// Let's do the example of the int32 field existence based on bit 0 in processing bitmask: 
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using FlagsField = nil::marshalling::types::BitmaskValue<MyFieldBase, nil::marshalling::option::fixed_length<1> >;
/// using OptField = 
///     nil::marshalling::types::Optional<
///         nil::marshalling::types::IntValue<MyFieldBase, std::int32_t>
///     >;
///
/// FlagsField flags;
/// OptField optField;
/// 
/// // Common read function for multiple buffers
/// auto readFunc = 
///     [&flags, &optField](const std::uint8_t*& iter, std::size_t len)
///     {
///         auto es = flags.read(iter, len);
///         assert(es == nil::marshalling::ErrorStatus::success); // No error is expected;
/// 
///         optField.set_missing();
///         if ((flags.value() & 0x1) != 0) {
///             optField.set_exists();
///         }
///
///         es = optField.read(iter, len - flags.length());
///         assert(es == nil::marshalling::ErrorStatus::success); // No error is expected;
///     };
///         
///
/// static const std::uint8_t InputBuffer1[] = {
///     0x1, 0xa, 0xb, 0xc, 0xd, 0xe, 0xf
/// }
/// static const auto InputBuffer1Size = std::extent<decltype(InputBuffer1)>::value;
///
/// auto* readIter = &InputBuffer1[0];
/// readFunc(readIter, InputBuffer1Size);
/// assert(std::distance(&InputBuffer1[0], readIter) == 5); // Expected to read 1 byte of flags and
///                                                         // 4 bytes of int32_t int value, because
///                                                         // bit 0 in flags is set.
/// assert(optField.field().value() == 0x0a0b0c0d); // value is expected to be updated;
///
///
///
/// static const std::uint8_t InputBuffer2[] = {
///     0x0, 0xa, 0xb, 0xc, 0xd, 0xe, 0xf
/// }
/// static const auto InputBuffer2Size = std::extent<decltype(InputBuffer2)>::value;
///
/// optField.field().value() = 0;
/// readIter = &InputBuffer2[0];
/// readFunc(readIter, InputBuffer2Size);
/// assert(std::distance(&InputBuffer2[0], readIter) == 1); // Expected to read only 1 byte of flags 
///                                                         // skipping read of int32_t int value, because
///                                                         // bit 0 in flags is cleared.
/// assert(optField.field().value() == 0); // value is expected NOT to be updated;
/// @endcode 
/// Note, that default mode for the optional field is "tentative", which is
/// updated after read operation:
/// @code
/// OptField optField1;
/// assert(optField1.get_mode() == nil::marshalling::types::OptionalMode::tentative); // Default mode is tentative
/// 
/// static const std::uint8_t InputBuffer[] = {
///     0x11, 0x22, 0x33, 0x44
/// }
/// static const auto InputBufferSize = std::extent<decltype(InputBuffer)>::value;
///
/// auto* readIter = &InputBuffer[0];
/// auto es = optField1.read(readIter, InputBufferSize);
/// assert(es = nil::marshalling::ErrorStatus::success);
/// assert(std::distance(&InputBuffer[0], readIter) == 4); // Expected to read 4 bytes of int32_t int value
/// assert(optField1.get_mode() == nil::marshalling::types::OptionalMode::exists); // mode_type is changed
///
/// OptField optField2;
/// assert(optField2.get_mode() == nil::marshalling::types::OptionalMode::tentative); // Default mode is tentative
/// readIter = &InputBuffer[0];
/// es = optField2.read(readIter, 0); // Note 0 as a buffer size
/// assert(es = nil::marshalling::ErrorStatus::success);
/// assert(std::distance(&InputBuffer[0], readIter) == 0); // Expected not to read anything
/// assert(optField2.get_mode() == nil::marshalling::types::OptionalMode::missing); // mode_type is changed
/// @endcode
/// It is easy to change the default mode of the nil::marshalling::types::Optional field by
/// providing nil::marshalling::option::default_optional_mode option with selected default mode
/// or @ref nil::marshalling::option::missing_by_default / @ref nil::marshalling::option::exists_by_default aliases.
/// @code
/// using OptField = 
///     nil::marshalling::types::Optional<
///         nil::marshalling::types::IntValue<MyFieldBase, std::int32_t>,
///         nil::marshalling::option::missing_by_default // Set default mode to be "missing"
///     >;
/// @endcode
/// Some protocols may include version information either in transport framing or
/// in one of the messages. Such info may specify whether a specific field exists
/// or not. Such fields need to be wrapped in @ref nil::marshalling::types::Optional field, which
/// receives @ref nil::marshalling::option::exists_between_versions option to specify the
/// numeric versions of the protocol between which the field exists.
/// @code
/// using OptField = 
///     nil::marshalling::types::Optional<
///         nil::marshalling::types::IntValue<MyFieldBase, std::int32_t>,
///         nil::marshalling::option::missing_by_default, // Set default mode to be "missing"
///         nil::marshalling::option::exists_between_versions<1, 5>
///     >;
/// @endcode
/// If the field has been introduced in one of the version, but hasn't been
/// removed yet, it is possible to use @ref nil::marshalling::option::exists_since_version alias
/// to @ref nil::marshalling::option::exists_between_versions. Or the opposite, if the field
/// has been introduced in the first version, but deprecated and removed in the 
/// later one, use @ref nil::marshalling::option::exists_until_version alias.
///
/// Usage of such version control option will automatically mark the optional
/// field as @b existing or @b missing based on the provided version info in
/// the @b set_version() member function.
///
/// @section sec_field_tutorial_variant Variant fields_type
/// Some protocols may require usage of heterogeneous fields or lists of 
/// heterogeneous fields, i.e. the ones that can be of multiple types. Good example
/// would be a list of @b properties, where every property is a key/value pair. The
/// key is a numeric ID of the property, while value can be a numeric field of
/// any length or a string one. As an example let's define three value types:
/// @li Unsigned integer with length of only 1 byte (@b Value1)
/// @li Unsigned integer with length of 4 bytes (@b Value2)
/// @li String field with 1 byte size prefix (@b Value3)
///
/// The @b Marshalling library provides nil::marshalling::types::Variant field to allow such
/// heterogeneous fields. Let's implement the described example.
///
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using Value1 = nil::marshalling::types::IntValue<MyFieldBase, std::uint8_t>;
/// using Value2 = nil::marshalling::types::IntValue<MyFieldBase, std::uint32_t>;
/// using Value3 = 
///     nil::marshalling::types::String<
///         MyFieldBase, 
///         nil::marshalling::option::sequence_size_field_prefix<
///             nil::marshalling::types::IntValue<
///                 MyFieldBase,
///                 std::uint8_t
///             >
///         >
///     >;
/// @endcode
/// The common key type is easy to represent as enum.
/// @code
/// enum class KeyId : std::uint8_t
/// {
///     Key1,
///     Key2,
///     Key3,
///     NumOfValues
/// };
/// @endcode
/// And the relevant key fields as a variant of nil::marshalling::types::EnumValue with
/// only single acceptable value.
/// @code
/// template <KeyId TId>
/// using KeyField =
///     nil::marshalling::types::EnumValue<
///         MyFieldBase,
///         KeyId,
///         nil::marshalling::option::default_num_value<(int)TId>,
///         nil::marshalling::option::valid_num_value_range<(int)TId, (int)TId>,
///         nil::marshalling::option::fail_on_invalid<>
///     >;
/// 
/// using Key1 = KeyField<KeyId::Key1>;
/// using Key2 = KeyField<KeyId::Key2>;
/// using Key3 = KeyField<KeyId::Key3>;
/// @endcode
/// Then the @b KeyX and its corresponding @b ValueX need to be bundled together
/// as a single @b PropertyX field.
/// @code
/// using Property1 = nil::marshalling::types::Bundle<MyFieldBase, std::tuple<Key1, Value1> >;
/// using Property2 = nil::marshalling::types::Bundle<MyFieldBase, std::tuple<Key2, Value2> >;
/// using Property3 = nil::marshalling::types::Bundle<MyFieldBase, std::tuple<Key3, Value3> >;
/// @endcode
/// Now we need a single @b field abstraction, which can be any of the specified
/// above forms. The nil::marshalling::types::Variant field class provides such an ability.
/// As its second parameter it receives a tuple of supported types.
/// @code
/// using MyVariant = 
///     nil::marshalling::types::Variant<
///         MyFieldBase,
///         std::tuple<Property1, Property1, Property3>
///     >;
/// @endcode 
/// Now it is easy to put such field type into the list:
/// @code
/// using PropertiesList = nil::marshalling::types::array_list<MyFieldBase, MyVariant>;
/// @endcode
/// In this scenario, read operation on the list will invoke read operation of
/// every @b MyVariant field, which in turn will try to perform read operation
/// on @b Property1, @b Property2, and @b Property3 in the order of their 
/// definition inside the provided tuple. The read operation of the
/// nil::marshalling::types::Variant field type will stop when read operation of any
/// of the contained types reports nil::marshalling::ErrorStatus::success as its status.
///
/// Accessing the currently held field can be tricky though. There is a need
/// to differentiate between @b compile-time and @b run-time knowledge of the
/// contents. 
///
/// When preparing a variant field to be sent out, usually the inner 
/// field type and its value are known at compile time. The initialisation of the
/// field can be performed using nil::marshalling::types::Variant::init_field() member
/// function:
/// @code
/// MyVariant var; // Created in "invalid" state
/// auto& prop1 = var.init_field<0>(); // Initialise as Propery1 due to 0 as provided index (constructor is called)
/// auto& prop1Value = std::get<1>(prop1.value()); // Access the "value" field of the bundle
/// prop1Value = 0xff; // Update the property value
/// @endcode
/// If the variant field has been initialised before, but there is a need to
/// to access the real type (also known at compile time), use
/// nil::marshalling::types::Variant::access_field() member function
/// @code
/// void updateProp1(MyVariant& var)
/// {
///     auto& prop1 = var.access_field<0>(); // Access as Property1 field (simple cast, no call to the constructor)
///     auto& prop1Value = std::get<1>(prop1.value()); // Access the "value" field of the bundle
///     prop1Value = 0xff; // Update the property value
/// }
/// @endcode
/// Just like with @ref sec_field_tutorial_bitfield and @ref sec_field_tutorial_bundle
/// it would be convenient to operate with internal type names, rather than hard coded
/// indices. In order to provide names for the available inner types, please
/// inherit from proper nil::marshalling::types::Variant field definition and
/// use MARSHALLING_VARIANT_MEMBERS_ACCESS() macro inside.
/// @code
/// struct MyVariant : public nil::marshalling::types::Variant<...>
/// {
///     MARSHALLING_VARIANT_MEMBERS_ACCESS(prop1, prop2, prop3);
/// };
/// @endcode
/// It would be equivalent to having the following types and functions defined
/// @code
/// struct MyVariant : public nil::marshalling::types::Variant<...>
/// {
///     enum FieldIdx {
///         FieldIdx_prop1,
///         FieldIdx_prop2,
///         FieldIdx_prop3,
///         FieldIdx_numOfValues
///     }
///
///     template <typename... TArgs>
///     auto initField_prop1(TArgs&&... args) -> decltype(init_field<FieldIdx_prop1>(std::forward<TArgs>(args)...))
///     {
///         return init_field<FieldIdx_prop1>(std::forward<TArgs>(args)...)
///     }
///
///     auto accessField_prop1() -> decltype(access_field<FieldIdx_prop1>())
///     {
///         return access_field<FieldIdx_prop1>();
///     }
///
///     auto accessField_prop1() const -> decltype(access_field<FieldIdx_prop1>())
///     {
///         return access_field<FieldIdx_prop1>();
///     }
///
///     template <typename... TArgs>
///     auto initField_prop2(TArgs&&... args) -> decltype(init_field<FieldIdx_prop2>(std::forward<TArgs>(args)...))
///     {
///         return init_field<FieldIdx_prop2>(std::forward<TArgs>(args)...)
///     }
///
///     auto accessField_prop2() -> decltype(access_field<FieldIdx_prop2>())
///     {
///         return access_field<FieldIdx_prop2>();
///     }
///
///     auto accessField_prop2() const -> decltype(access_field<FieldIdx_prop2>())
///     {
///         return access_field<FieldIdx_prop2>();
///     }
///
///     template <typename... TArgs>
///     auto initField_prop3(TArgs&&... args) -> decltype(init_field<FieldIdx_prop3>(std::forward<TArgs>(args)...))
///     {
///         return init_field<FieldIdx_prop3>(std::forward<TArgs>(args)...)
///     }
///
///     auto accessField_prop3() -> decltype(access_field<FieldIdx_prop3>())
///     {
///         return access_field<FieldIdx_prop3>();
///     }
///
///     auto accessField_prop3() const -> decltype(access_field<FieldIdx_prop3>())
///     {
///         return access_field<FieldIdx_prop3>();
///     }
/// };
/// @endcode
/// @b NOTE, that the provided names have propagated into definition of @b FieldIdx
/// enum as well as all @b initField_* and @b accessField_* functions.
///
/// There are cases (such as after "read" operation), when actual type of the
/// @b Variant field is known at run-time. The most straightforward way of
/// inquiring the actual type index using nil::marshalling::types::Variant::current_field()
/// function and then using a `switch` statement and handle every case accordingly
/// may work but is not very efficient. There is a way to perform more efficient
/// way of dispatching the actual field to its appropriate handling function by
/// using nil::marshalling::types::Variant::current_field_exec() member function. It expects
/// to receive a handling object which can handle all of the available inner types:
/// @code
/// struct MyVariantHandler
/// {
///     template <std::size_t TIdx>
///     void operator()(Property1& prop) {...}
///
///     template <std::size_t TIdx>
///     void operator()(Property2& prop) {...}
///
///     template <std::size_t TIdx>
///     void operator()(Property3& prop) {...}
/// }
///
/// void handleVariant(MyVariant& var)
/// {
///     var.current_field_exec(MyVariantHandler());
/// }
/// @endcode
/// @b NOTE, that every @b operator() function receives a compile time index
/// of the handed field within a containing tuple. If it's not needed when
/// handling the member field, just ignore it or static_assert on its value if
/// the index's value is known.
///
/// The class of the handling object may also receive the handled member type
/// as a template parameter
/// @code
/// struct MyVariantHandler
/// {
///     template <std::size_t TIdx, typename TField>
///     void operator()(TField& prop) {...}
/// }
/// @endcode
/// The default constructed nil::marshalling::types::Variant object from the examples above
/// has an "invalid" state, i.e. hasn't been initialised and doesn't contain any
/// valid field. It can be changed by providing nil::marshalling::option::default_variant_index
/// option.
/// @code
/// struct MyVariant : public 
///     nil::marshalling::types::Variant<
///         MyFieldBase,
///         std::tuple<Property1, Property1, Property3>,
///         nil::marshalling::option::default_variant_index<0> // Initialise as Prop1
///     >
/// {
///     MARSHALLING_VARIANT_MEMBERS_ACCESS(prop1, prop2, prop3);
/// };
/// @endcode 
/// When instantiating such @b MyVariant object, there is no need to perform
/// initialisation (construction) of the contained object
/// @code
/// MyVariant var;
/// assert(var.current_field_valid());
/// assert(var.current_field() == 0U); // Make sure the current index is 0
/// auto& prop1 = var.accessField_prop1(); // Get access to Property1 interface
/// auto& value1 = std::get<1>(prop1.value()); // Get access to the "value" field in the bundle
/// value1.value() = 0xff; // Assign the value
/// @endcode
/// <b style="color:red">WARNING:</b> Some compilers, such as @b clang or earlier
/// versions of @b gcc (v4.9 and earlier) may have problems compiling the 
/// @ref MARSHALLING_VARIANT_MEMBERS_ACCESS() macro
/// even though it contains valid C++11 code. If the compilation failure 
/// happens and the variant definition class is @b NOT a template one (like
/// in the example above), then try to substitute the used macro with
/// @ref MARSHALLING_VARIANT_MEMBERS_ACCESS_NOTEMPLATE(). For example:
/// @code
/// struct MyVariant : public 
///     nil::marshalling::types::Variant<
///         MyFieldBase,
///         std::tuple<Property1, Property1, Property3>,
///         nil::marshalling::option::default_variant_index<0> // Initialise as Prop1
///     >
/// {
///     MARSHALLING_VARIANT_MEMBERS_ACCESS_NOTEMPLATE(prop1, prop2, prop3);
/// };
/// @endcode 
/// However, when the defined variant class is a template, then the inner
/// definition of @b Base type, which specifies the exact type of the base
/// class, is required. For example:
/// @code
/// template <typename... TExtraOptions>
/// class MyVariant : public 
///     nil::marshalling::types::Variant<
///         MyFieldBase,
///         std::tuple<Property1, Property1, Property3>,
///         nil::marshalling::option::default_variant_index<0>, // Initialise as Prop1
///         TExtraOptions...
///     >
/// {
///     // Duplicate base class definition
///     using Base =
///         nil::marshalling::types::Variant<
///             MyFieldBase,
///             std::tuple<Property1, Property1, Property3>,
///             nil::marshalling::option::default_variant_index<0>, // Initialise as Prop1
///             TExtraOptions...
///         >;
/// public:
///     MARSHALLING_VARIANT_MEMBERS_ACCESS(prop1, prop2, prop3);
/// };
/// @endcode
/// @b NOTE, that @b Marshalling library also defines @b MARSHALLING_MUST_DEFINE_BASE in
/// case the base class definition is needed (going to be used). If the developed
/// application is going to be multi-platform and compiled with various compilers
/// (some of which may warn about unused private type) it is possible to use 
/// the defined symbol to add / remove the definition of the @b Base member type.
/// @code
/// template <typename... TExtraOptions>
/// class MyVariant : public nil::marshalling::types::Variant<...>
/// {
/// #ifdef MARSHALLING_MUST_DEFINE_BASE
///     using Base = ...;
/// #endif
/// public:
///     MARSHALLING_VARIANT_MEMBERS_ACCESS(prop1, prop2, prop3);
/// };
/// @endcode
/// 
/// @section sec_field_tutorial_common_options Common options_type or Modifications for the fields_type
/// There are options that suitable only to numeric fields, such as 
/// nil::marshalling::types::IntValue, nil::marshalling::types::EnumValue, nil::marshalling::types::BitmaskValue. @n
/// There are options that suitable only for collection fields, such as
/// nil::marshalling::types::array_list, and nil::marshalling::types::String.@n
/// There are also @b common options that can be used with all the fields that support
/// options.
///
/// @subsection sec_field_tutorial_common_options_default_value Default value for Default Construction
/// There may be a case when default construction of the field object should
/// assign some custom value to the field, which differ to the usual defaults, such
/// as assigning 0 to numeric fields or empty string to a string field. 
/// 
/// One of the possible ways is to extend the defined field class and 
/// set the required value in the constructor.
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// struct MyString : public nil::marshalling::types::String<MyFieldBase>
/// {
///     MyString()
///     {
///         value() = "hello";
///     }
/// };
/// @endcode
/// Another way is to use nil::marshalling::option::default_value_initialiser option.
/// It receives a template parameter, which has to be a type of initialisation
/// class. It must provide @b operator() which is responsible to assign a custom
/// value to the field. It is going to be invoked from the default constructor
/// of the field.
/// @code
/// struct Initaliser
/// {
///     template <typename TField>
///     void operator()(TField& field)
///     {
///         field.value() = ...; // Set the default value here
///     }
/// };
/// @endcode
/// For example:
/// @code
/// struct CustomStringInitaliser
/// {
///     template <typename TField>
///     void operator()(TField& field)
///     {
///         field.value() = "hello"
///     }
/// };
///
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using MyString = 
///     nil::marshalling::types::String<
///         MyFieldBase, 
///         nil::marshalling::option::default_value_initialiser<CustomStringInitaliser>
///     >;
///
/// MyString myStr; // Default construction
/// assert(myStr.value() == "hello"); // Custom default value is expected to be assigned
/// @endcode
/// @b NOTE that the used @b operator() specifies the field type as a template
/// parameter. This is required because the passed reference is to one of the
/// defined field's base classes, which is implementation dependent. Just use
/// the provided @b value() member function to access the value.
///
/// The Marshalling library also provides a simpler alias for nil::marshalling::option::default_value_initialiser
/// to set default value for numeric fields. It is nil::marshalling::option::default_num_value.
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using MyInt = 
///     nil::marshalling::types::IntValue<
///         MyFieldBase, 
///         std::uint16_t,
///         nil::marshalling::option::default_num_value<10>
///     >;
/// 
/// MyInt myInt;
/// assert(myInt.value() == 10); // Custom default value is expected to be assigned
/// @endcode
///
/// @subsection sec_field_tutorial_common_options_read Custom Read Functionality
/// Every field provides @b read() member function to perform read of the field's
/// value. Sometimes the default "read" functionality may be incorrect or
/// incomplete. For example, let's
/// define a "bundle" field with two members. The first one is a "bitmask", while
/// the second one is optional 2 byte "int" value. The second member exists 
/// only if least significant bit of the "bitmask" is not @b 0. In this case, 
/// the provided @b read() member function won't analyse the value of the
/// read "bitmask" and won't modify "existing"/"missing" mode value of the
/// optional field.
///
/// One way to implement custom read functionality is to extend the field
/// definition and override the @b read() member function:
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// struct MyBundle : public 
///     nil::marshalling::types::Bundle<
///         MyFieldBase,
///         std::tuple<
///             nil::marshalling::types::BitmaskValue<MyFieldBase, nil::marshalling::option::fixed_length<1> >,
///             nil::marshalling::types::Optional<MyFieldBase, std::uint16_t>
///         >,
///         nil::marshalling::option::has_custom_read
///     >
/// {
///     template <typename TIter>
///     nil::marshalling::ErrorStatus read(TIter& iter, std::size_t len)
///     {
///         auto& members = value();
///         auto& bitmask = std::get<0>(members);
///         auto& optInt = std::get<1>(members);
///         
///         auto es = bitmask.read(iter, len);
///         if (es != nil::marshalling::ErrorStatus::success) {
///             return es;
///         }
///
///         if (bitmask.get_bit_value(0)) {
///             optInt.set_exists();
///         }
///         else {
///             optInt.set_missing();
///         }
///
///         return optInt.read(iter, len - bitmask.length());
///     }
/// };
/// @endcode
/// @b NOTE the usage of @ref nil::marshalling::option::has_custom_read option. It notifies
/// other classes about existence of custom @b read functionality 
/// (instead of default one). Other classes may contain some inner logic to
/// perform various optimisations if there is no custom @b read.
/// Failure to specify this option may result in incorrect behaviour.
///
/// Another way is to use nil::marshalling::option::custom_value_reader option. It
/// receives one template parameter, which has to be a type of a custom
/// reader class. Such class must implement @b operator() with the following
/// signature:
/// @code
/// struct MyReader
/// {
///     template <typename TField, typename TIter>
///     nil::marshalling::ErrorStatus operator()(TField& field, TIter& iter, std::size_t len) const
///     {
///         ... // Do proper read of the field's value.
///     }
/// };
/// @endcode
/// @b NOTE that the used @b operator() specifies the field type as a template
/// parameter. This is required because the passed reference is to one of the
/// defined field's base classes, which is implementation dependent. Just use
/// the provided @b value() member function to access the tuple of member fields.
/// 
/// @subsection sec_field_tutorial_common_options_validation Custom value Validation Logic
/// Every field provides @b valid() member function to validate the internal value.
/// By default, every internal value of the field is considered to be valid, i.e.
/// the @b valid() function will always return true. 
///
/// One of the ways to provide custom validation logic is to extend the field
/// definition and implement @b valid() member function:
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// struct MyString : public nil::marshalling::types::String<MyFieldBase>
/// {
///     bool valid() const
///     {
///         // Valid if not empty and starts with '$'
///         return (!value().empty()) && (value()[0] == '$');
///     }
/// };
/// @endcode
/// 
/// Another way is to use nil::marshalling::option::contents_validator option. It
/// receives one template parameter, which has to be a type of a custom
/// validator class. Such class must implement @b operator() with the following
/// signature:
/// @code
/// struct MyValidator
/// {
///     template <typename TField>
///     bool operator()(const TField& field)
///     {
///         auto& value = field.value();
///         return (... /* Check value */); // return true if valid.
///     }
/// };
/// @endcode
/// For example:
/// @code
/// struct CustomStringValidator
/// {
///     template <typename TField>
///     bool operator()(const TField& field)
///     {
///         // Valid if not empty and starts with '$'
///         auto& str = field.value();
///         return (!str.empty()) && (str[0] == '$');
///     }
/// };
///
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using MyString = nil::marshalling::types::String<
///     MyFieldBase, 
///     nil::marshalling::option::contents_validator<CustomStringValidator>
///  >;
///
/// MyString myStr; 
/// assert(!myStr.valid()); // Default construction creates empty string - invalid
/// 
/// myStr.value() = "$somestring";
/// assert(myStr.valid()); // Now the string is as expected
/// @endcode
/// @b NOTE that the used @b operator() specifies the field type as a template
/// parameter. This is required because the passed reference is to one of the
/// defined field's base classes, which is implementation dependent. Just use
/// the provided @b value() member function to access the value.
///
/// Quite often the valid values of the numeric fields can be expressed in limited
/// number of ranges: [minValid - maxValid]. The Marshalling library provides
/// @ref nil::marshalling::option::valid_num_value_range option (and @ref nil::marshalling::option::ValidNumValue alias),
/// which can be used multiple times. The field's value is considered to be valid if
/// <b>at least one</b> of the provided ranges contains it. The range validation option
/// can be used only with numeric value fields, such as nil::marshalling::types::IntValue,
/// or nil::marshalling::types::EnumValue. For example:
/// @code
/// enum SomeEnum : std::uint8_t
/// {
///     SomeEnum_Value1 = 1,
///     SomeEnum_Value2,
///     SomeEnum_Value3
/// };
///
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using MyEnum = 
///     nil::marshalling::types::EnumValue<
///         MyFieldBase, 
///         SomeEnum,
///         nil::marshalling::option::default_num_value<SomeEnum_Value1>, // Construct with valid value
///         nil::marshalling::option::valid_num_value_range<SomeEnum_Value1, SomeEnum_Value3>
///     >;
///
/// MyEnum myEnum;
/// assert(myEnum.value() == SomeEnum_Value1);
/// assert(myEnum.valid());
///
/// myEnum.value() = static_cast<SomeEnum>(0); // Assigning invalid value.
/// assert(!myEnum.valid()); // The field being invalid must be reported
/// @endcode
///
/// Another example could be a single character numeric field with valid values
/// range of [0x20 - 0x7e], as well as value 0. Such field can be defined as:
/// @code
/// using MyChar = 
///     nil::marshalling::types::IntValue<
///         MyFieldBase,
///         char,
///         nil::marshalling::option::valid_num_value_range<0x20, 0x7e>,
///         nil::marshalling::option::ValidNumValue<0>
///     >;
/// @endcode
/// @b WARNING: Some older compilers (@b gcc-4.7) fail to compile valid C++11 code
/// that allows usage of multiple @ref nil::marshalling::option::valid_num_value_range options. If this is
/// the case, please don't pass more than one @ref nil::marshalling::option::valid_num_value_range option.
///
/// There is a also a convenience alias to nil::marshalling::option::contents_validator intended
/// for use with bitmasks (nil::marshalling::types::BitmaskValue). Many bitmask fields
/// may have one or several reserved bits with predefined values they must contain.
/// The alias option is nil::marshalling::option::bitmask_reserved_bits. It receives two
/// template parameters: one for the mask indicating the reserved bits and another
/// for the expected values of these bits.@n
/// For example, below is a definition of the 1 byte bitmask field that has
/// two reserved bits, most and least significant. Both of them must be 0.
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using MyFlags = 
///     nil::marshalling::types::BitmaskValue<
///         MyFieldBase, 
///         nil::marshalling::option::fixed_length<1>,
///         nil::marshalling::option::bitmask_reserved_bits<0x81, 0>
///     >;
///
/// MyFlags flags;
/// assert(myEnum.valid());
/// flags.value() |= 0x1; // set bit 0;
/// assert(!flags.valid()); // the field is invalid now.
/// @endcode
///
/// @subsection sec_field_tutorial_common_options_refresh Custom Refresh Functionality
/// Every field provides @b refresh() member function used to bring the field's 
/// value into a consistent state. By default this function does nothing and
/// returns @b false, meaning the field has @b NOT been updated. For complex fields, such
/// as nil::marshalling::types::Bitfield or nil::marshalling::types::Bundle, the default behaviour is
/// to invoke @b refresh() member function of each member field and return @b true
/// if @b any of the calls returned true.
///
/// One way to change such default behaviour is to extend the field
/// definition and implement @b refresh() member function. Let's take the
/// same example as in @ref sec_field_tutorial_common_options_read section. There is
/// a "bundle" field with two members. The first one is a "bitmask", while
/// the second one is optional 2 byte "int" value. The second member exists 
/// only if least significant bit of the "bitmask" is not @b 0. There is a 
/// chance of having inconsistent state when the least significant bit in
/// the "bitmask" is set, but the optional "int" field is marked to be "missing".
/// There is a need to provide the custom "refresh" logic that brings the field's
/// contents into a consistent state.
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// struct MyBundle : public 
///     nil::marshalling::types::Bundle<
///         MyFieldBase,
///         std::tuple<
///             nil::marshalling::types::BitmaskValue<MyFieldBase, nil::marshalling::option::fixed_length<1> >,
///             nil::marshalling::types::Optional<MyFieldBase, std::uint16_t>
///         >,
///         nil::marshalling::option::has_custom_read,
///         nil::marshalling::option::has_custom_refresh
///     >
/// {
///     ... 
///
///     bool refresh()
///     {
///         auto& members = value();
///         auto& bitmask = std::get<0>(members);
///         auto& optInt = std::get<1>(members);
///         auto expectedMode = nil::marshalling::types::OptionalMode::missing;
///         if (bitmask.get_bit_value(0)) {
///             expectedMode = nil::marshalling::types::OptionalMode::exists;
///         }
///
///         if (optInt.get_mode() == expectedMode) {
///             return false; // Nothing has been changed
///         }
///     
///         optInt.set_mode(expectedMode);
///         return true; // field_type has been updated
///     }
/// };
/// @endcode
/// @b NOTE the usage of @ref nil::marshalling::option::has_custom_refresh option. It notifies
/// other classes about existence of custom @b refresh functionality 
/// (instead of default one). Other classes may contain some inner logic to
/// perform various optimisations if there is no custom @b refresh.
/// Failure to specify this option may result in incorrect behaviour.
/// 
/// Another way is to use nil::marshalling::option::contents_refresher option. It
/// receives one template parameter, which has to be a type of a custom
/// refresher class. Such class must implement @b operator() with the following
/// signature:
/// @code
/// struct MyRefresher
/// {
///     template <typename TField>
///     bool operator()(TField& field)
///     {
///         ... // return true if field was modified, false otherwise
///     }
/// };
/// @endcode
/// @b NOTE that the used @b operator() specifies the field type as a template
/// parameter. This is required because the passed reference is to one of the
/// defined field's base classes, which is implementation dependent. Just use
/// the provided @b value() member function to access the value.
///
/// @subsection sec_field_tutorial_common_options_version Custom Version Update Functionality
/// Some protocols may include version information either in the transport framing
/// of every message or in one of the messages used to establish connection. Such
/// info may influence whether some fields exist, as well as modify other
/// aspects of the fields, such as validity ranges. 
///
/// Every field provides @b set_version() member function used to notify it about
/// the version change and @b is_version_dependent() one to inquire at compile time
/// whether the field contents may change after such notification. 
/// For most fields @b set_version() function does nothing and
/// returns @b false, meaning the field has @b NOT been updated (similar to
/// @ref sec_field_tutorial_common_options_refresh). For complex fields, such
/// as nil::marshalling::types::Bitfield or nil::marshalling::types::Bundle, the default behaviour is
/// to invoke @b set_version() member function of each member field and return @b true
/// if @b any of the calls returned @b true. For @ref nil::marshalling::types::array_list
/// fields, the version information may be stored inside (only if the element's
/// @b is_version_dependent() member function returns @b true) and used to notify
/// every new field that is being read during @b read operation.
///
/// Usually, the default version handling provided by the @b Marshalling library is
/// good enough. However, there may be cases when custom operation needs to
/// be performed during version update. For example, there is integral value
/// field with valid values range [0, 5]. There is a need to report field as
/// being invalid for any other numbers for all version up to @b 5. However, since
/// version @b 6 the range is extended to [0, 10]. It can be defined as following:
/// @code
/// class MyInt : public
///     nil::marshalling::types::IntValue<
///         MyFieldBase,
///         std::uint8_t,
///         nil::marshalling::option::valid_num_value_range<0, 5>,
///         nil::marshalling::option::has_custom_version_update
/// {
///     using Base = nil::marshalling::types::IntValue<...>; // Repeat base class definition
/// public:
///     // Updated validity check
///     bool valid() const
///     {
///         if (Base::valid()) {
///             return true;
///         }
///         
///         if (m_version < 6) {
///             return false;
///         }
///
///         return value() <= 10;
///     }
///
///     // Updated version set
///     // Store version internally for future references
///     bool set_version(version_type version)
///     {
///         m_version = version;
///         return Base::set_version(version);
///     }
///
/// private:
///     version_type m_version = 0;
/// };
/// @endcode
/// @b NOTE, the usage of @ref nil::marshalling::option::has_custom_version_update option. It
/// marks the defined field as "version dependent" and as the result its @b
/// is_version_dependent() member function will return @b true.
///
/// Also @b NOTE, that by default the @b version_type inner type is defined to
/// be @b unsigned. If there is a need to change that, the @ref
/// nil::marshalling::option::version_type needs to be passed to the definition of the
/// common base class of all the fields:
/// @code
/// using MyFieldBase = 
///     nil::marshalling::field_type<
///         nil::marshalling::option::big_endian,
///         nil::marshalling::option::version_type<unsigned long long>
///     >;
/// @endcode
///
/// @subsection sec_field_tutorial_common_options_fail_invalid Fail on Invalid value
/// Sometimes the protocol specifications may impose a strict rules on disallowing
/// invalid values, such as the message must be dropped when some field has
/// an invalid value. It is easy to implement by forcing @b read() operation on
/// such field to fail when reading an invalid value is recognised. The Marshalling
/// library provides nil::marshalling::option::fail_on_invalid option to help with such task.
/// For example:
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using MyField = 
///     nil::marshalling::types::IntValue<
///         MyFieldBase,
///         std::uint8_t,
///         nil::marshalling::option::valid_num_value_range<0, 5>,
///         nil::marshalling::option::fail_on_invalid
///     >;
///
/// static const std::uint8_t InvalidBuf[] = { 0x6 };
/// static const auto InvalidBufSize = std::extent<decltype(InvalidBuf)>::value;
///
/// MyField myField;
/// auto* readIter = &InvalidBuf[0];
/// auto es = myField.read(readIter, InvalidBufSize);
/// assert(es != nil::marshalling::ErrorStatus::success); // Read failure is expected
///
/// static const std::uint8_t ValidBuf[] = { 0x1 };
/// static const auto ValidBufSize = std::extent<decltype(ValidBuf)>::value;
///
/// readIter = &ValidBuf[0];
/// es = myField.read(readIter, ValidBufSize);
/// assert(es == nil::marshalling::ErrorStatus::success); // Read operation is expected to be successful now
/// @endcode
///
/// @subsection sec_field_tutorial_common_options_ignore_invalid Ignore Invalid value
/// The Marshalling library also provides nil::marshalling::option::ignore_invalid option. It DOESN'T
/// report failure on read operation when the invalid value is discovered 
/// (like nil::marshalling::option::fail_on_invalid does). Instead the field's internal value
/// remains unchanged, although the read iterator is advanced as if the value
/// is read. For example:
/// @code
/// using MyFieldBase = nil::marshalling::field_type<nil::marshalling::option::big_endian>;
/// using MyField = nil::marshalling::types::IntValue<
///     MyFieldBase,
///     std::uint8_t,
///     nil::marshalling::option::valid_num_value_range<0, 5>,
///     nil::marshalling::option::ignore_invalid
/// >;
///
/// static const std::uint8_t InvalidBuf[] = { 0x6 };
/// static const auto InvalidBufSize = std::extent<decltype(InvalidBuf)>::value;
///
/// MyField myField;
/// assert(myField.valid());
/// assert(myField.value() == 0U);
///
/// auto* readIter = &InvalidBuf[0];
/// auto es = myField.read(readIter, InvalidBufSize);
/// assert(es == nil::marshalling::ErrorStatus::success); // No failure is expected
/// assert(myField.value() == 0U); // value mustn't be changed
///
/// static const std::uint8_t ValidBuf[] = { 0x1 };
/// static const auto ValidBufSize = std::extent<decltype(ValidBuf)>::value;
///
/// readIter = &ValidBuf[0];
/// es = myField.read(readIter, ValidBufSize);
/// assert(es == nil::marshalling::ErrorStatus::success); // No failure is expected
/// assert(myField.value() == 1U); // value is expected to be updated
/// @endcode
///
/// @subsection sec_field_tutorial_common_options_empty_ser Empty Serialisation
/// Some protocols may define some constants which are NOT being sent over I/O
/// link. Sometimes it may be useful to still treat these values as message fields.
/// Usage of @ref nil::marshalling::option::empty_serialization (or @ref
/// nil::marshalling::option::EmptySerialisation for those who prefer British spelling) can
/// be used to achieve such effect.
/// @code
/// using MyField = nil::marshalling::types::IntValue<
///     MyFieldBase,
///     std::uint8_t,
///     nil::marshalling::option::valid_num_value_range<5, 5>,
///     nil::marshalling::option::default_num_value<5>,
///     nil::marshalling::option::empty_serialization
/// >;
/// 
/// MyField field;
/// assert(field.length() == 0U); // Not expected to have any serialization length
/// assert(field.value() == 5U); // The value is still accessible;
///
/// std::vector<std::uint8_t> outBuf;
/// auto writeIter = std::back_inserter(outBuf);
/// auto es == field.write(writeIter, outBuf.max_size());
/// assert(es == nil::marshalling::ErrorStatus::success); // No failure is expected
/// assert(outBuf.empty()); // No data has been written
/// @endcode
///
/// @section sec_field_tutorial_extension Allowing Further Use of options_type
/// As was mentioned earlier there are options that define how fields are
/// (de)serialized. These options are expected to be used in protocol fields
/// definition. However, there are options that are application specific. They
/// may change the data structures being used for storage, or modify default
/// value and/or valid values. In order to allow such application specific modifications,
/// the defined fields should allow further extension, for example with extra
/// variadic template arguments.
/// @code
/// template <typename... TExtraOpts>
/// using MyField = 
///     nil::marshalling::types::IntValue<
///         nil::marshalling::field_type<nil::marshalling::option::big_endian>, // base class of the field
///         std::uint16_t,
///         TExtraOpts...,
///         nil::marshalling::option::default_num_value<5>,
///         nil::marshalling::option::valid_num_value_range<5, 1000>
/// @endcode
/// Please @b note, that current implementation gives preference to the options
/// defined @b earlier. That's why @b TExtraOpts... should be listed before any
/// other options. It will allow setting other default value needed by the application,
/// and/or override the valid values ranges (using @ref nil::marshalling::option::valid_ranges_clear).
/// For example:
/// @code
/// using MyUpdatedField = 
///     MyField<
///         nil::marshalling::option::default_num_value<10>,
///         nil::marshalling::option::valid_num_value_range<10, 500>,
///         nil::marshalling::option::valid_ranges_clear
///     >
/// @endcode
///
/// @section sec_field_tutorial_custom_fields Custom fields_type
/// There may be a case when communication protocol demands implementation of
/// some intricate field's logic that is not covered by the Marshalling library. It
/// is possible to provide custom implementation of the custom field and use
/// it with other components provided by the library as long as it defines 
/// the following minimal interface:
/// @code
/// class MyField
/// {
/// public:
///     
///     // length required to serialise current value
///     std::size_t length() const;
///
///     // Minimal length required to serialise any value this field may contain
///     static constexpr std::size_t min_length();
///
///     // Maximal length required to serialise any value this field may contain.
///     static constexpr std::size_t max_length();
///
///     // Check validity of the internal value
///     bool valid() const;
///
///     // Bring field's value into the consistent state,
///     // return true if the field's value has been updated, false otherwise
///     bool refresh();
///
///     // Read field value from input data sequence, using any type of input iterator
///     template <typename TIter>
///     nil::marshalling::ErrorStatus read(TIter& iter, std::size_t size);
///
///     // Write field value to output data sequence, using any type of output iterator
///     template <typename TIter>
///     nil::marshalling::ErrorStatus write(TIter& iter, std::size_t size) const;
/// };
/// @endcode
/// The nil::marshalling::field_type class provides @b read_data() and @b write_data() protected
/// member functions that serialise data using endian provided as an option
/// to the class. It makes sense to inherit from nil::marshalling::field_type with right
/// option and reuse these functions inside:
/// @code
/// class MyField : public nil::marshalling::field_type<nil::marshalling::option::big_endian>
/// {
/// public:
///     
///     ...
/// 
///     template <typename TIter>
///     nil::marshalling::ErrorStatus read(TIter& iter, std::size_t size)
///     {
///         ...
///         auto val = read_data<InternalType>(iter);
///         ...
///     }
///
///     template <typename TIter>
///     nil::marshalling::ErrorStatus write(TIter& iter, std::size_t size) const
///     {
///         ...
///         write_data(..., iter);
///         ...
///     }
/// };
/// @endcode
/// Also to be consistent with the existing implementation of the fields
/// in the Marshalling library it is recommended to provide an accessor functions
/// @b value() for internal data storage:
/// @code
/// class MyField : public nil::marshalling::field_type<nil::marshalling::option::big_endian>
/// {
/// public:
///     using value_type = ...;
/// 
///     value_type& value() {...}
///
///     const value_type& value() const {...}
/// };
/// @endcode
///
/// @section sec_field_tutorial_other_fields Other fields_type
/// With time the Marshalling library may grow by adding support for some other
/// built-in fields as well as supporting extra options to the existing
/// fields described in this tutorial. If such new field and/or option is
/// not described in this tutorial, it should be easy enough for the developer
/// to master. Please refer to the documentation of the field and/or option 
/// itself.
///

